json-humanized 2.0.0 → 2.0.1

package/README.md

@@ -1,8 +1,8 @@
 <div align="center">
 
-# json-humanized
+# 🗣️ json-humanized
 
-**Transform any JSON / YAML / TOML into natural human language**
+**📢Transform any JSON / YAML / TOML into natural human language**
 
 [![npm version](https://img.shields.io/npm/v/json-humanized?color=00e5ff&style=flat-square)](https://www.npmjs.com/package/json-humanized)
 [![CI](https://img.shields.io/github/actions/workflow/status/AceAnomDev/json-humanized/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/AceAnomDev/json-humanized/actions)

package/docs/DEMO.html

@@ -4,190 +4,59 @@
 <meta charset="UTF-8">
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>json-humanized — Live Demo</title>
+<!-- js-yaml for YAML parsing -->
+<script src="https://cdnjs.cloudflare.com/ajax/libs/js-yaml/4.1.0/js-yaml.min.js"></script>
 <style>
   @import url('https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;600&family=Syne:wght@400;700;800&display=swap');
   :root {
-    --bg: #0d0d12;
-    --panel: #14141f;
-    --border: #252535;
-    --cyan: #00e5ff;
-    --green: #00ff9d;
-    --yellow: #ffd166;
-    --red: #ff6b6b;
-    --text: #e0e0f0;
-    --muted: #6060a0;
-    --radius: 12px;
+    --bg:#0d0d12; --panel:#14141f; --border:#252535;
+    --cyan:#00e5ff; --green:#00ff9d; --yellow:#ffd166;
+    --red:#ff6b6b; --text:#e0e0f0; --muted:#6060a0;
+    --radius:12px;
   }
-  * { box-sizing: border-box; margin: 0; padding: 0; }
-  body {
-    background: var(--bg);
-    color: var(--text);
-    font-family: 'Syne', sans-serif;
-    min-height: 100vh;
-    display: grid;
-    grid-template-rows: auto 1fr auto;
-  }
-  header {
-    padding: 32px 48px 24px;
-    border-bottom: 1px solid var(--border);
-    display: flex;
-    align-items: center;
-    gap: 20px;
-  }
-  header h1 {
-    font-size: 1.6rem;
-    font-weight: 800;
-    letter-spacing: -0.03em;
-  }
-  header h1 span { color: var(--cyan); }
-  header .badge {
-    font-family: 'JetBrains Mono', monospace;
-    font-size: 0.7rem;
-    background: var(--cyan)22;
-    color: var(--cyan);
-    border: 1px solid var(--cyan)44;
-    padding: 3px 10px;
-    border-radius: 99px;
-  }
-  header .links { margin-left: auto; display: flex; gap: 12px; }
-  header .links a {
-    font-size: 0.8rem;
-    color: var(--muted);
-    text-decoration: none;
-    transition: color .2s;
-  }
-  header .links a:hover { color: var(--cyan); }
-
-  main { display: grid; grid-template-columns: 1fr 1fr; gap: 0; }
-  .pane {
-    padding: 32px 40px;
-    display: flex;
-    flex-direction: column;
-    gap: 16px;
-  }
-  .pane + .pane { border-left: 1px solid var(--border); }
-  .pane-label {
-    font-size: 0.7rem;
-    font-weight: 700;
-    letter-spacing: .12em;
-    text-transform: uppercase;
-    color: var(--muted);
-    display: flex;
-    align-items: center;
-    gap: 8px;
-  }
-  .pane-label .dot {
-    width: 8px; height: 8px; border-radius: 50%;
-  }
-  .dot-cyan   { background: var(--cyan); }
-  .dot-green  { background: var(--green); }
-
-  textarea, #output {
-    flex: 1;
-    min-height: 340px;
-    font-family: 'JetBrains Mono', monospace;
-    font-size: 0.82rem;
-    line-height: 1.7;
-    background: var(--panel);
-    border: 1px solid var(--border);
-    border-radius: var(--radius);
-    padding: 20px;
-    color: var(--text);
-    resize: none;
-    outline: none;
-    transition: border-color .2s;
-  }
-  textarea:focus { border-color: var(--cyan)66; }
-  #output {
-    white-space: pre-wrap;
-    overflow-y: auto;
-    color: #c0c0e0;
-  }
-  #output.placeholder { color: var(--muted); font-style: italic; }
-  #output.loading     { color: var(--cyan); animation: pulse 1s ease-in-out infinite; }
-  #output.error       { color: var(--red); }
-  @keyframes pulse { 0%,100%{opacity:1} 50%{opacity:.5} }
-
-  .controls {
-    display: flex;
-    flex-wrap: wrap;
-    gap: 10px;
-    align-items: center;
-  }
-  select {
-    background: var(--panel);
-    border: 1px solid var(--border);
-    color: var(--text);
-    padding: 8px 12px;
-    border-radius: 8px;
-    font-family: 'Syne', sans-serif;
-    font-size: 0.8rem;
-    outline: none;
-    cursor: pointer;
-    transition: border-color .2s;
-  }
-  select:hover { border-color: var(--cyan)55; }
-
-  #run-btn {
-    margin-left: auto;
-    background: var(--cyan);
-    color: #000;
-    border: none;
-    padding: 10px 28px;
-    border-radius: 8px;
-    font-family: 'Syne', sans-serif;
-    font-weight: 700;
-    font-size: 0.85rem;
-    cursor: pointer;
-    transition: transform .15s, opacity .15s;
-    letter-spacing: .04em;
-  }
-  #run-btn:hover  { opacity: .9; transform: translateY(-1px); }
-  #run-btn:active { transform: translateY(0); }
-  #run-btn:disabled { opacity: .5; cursor: not-allowed; transform: none; }
-
-  .samples {
-    display: flex;
-    gap: 8px;
-    flex-wrap: wrap;
-  }
-  .sample-btn {
-    background: transparent;
-    border: 1px solid var(--border);
-    color: var(--muted);
-    padding: 5px 12px;
-    border-radius: 6px;
-    font-family: 'JetBrains Mono', monospace;
-    font-size: 0.72rem;
-    cursor: pointer;
-    transition: all .2s;
-  }
-  .sample-btn:hover { border-color: var(--cyan)66; color: var(--cyan); }
-
-  footer {
-    padding: 16px 48px;
-    border-top: 1px solid var(--border);
-    font-size: 0.72rem;
-    color: var(--muted);
-    display: flex;
-    justify-content: space-between;
-  }
-  footer a { color: var(--muted); text-decoration: none; }
-  footer a:hover { color: var(--cyan); }
-
-  .info-bar {
-    font-family: 'JetBrains Mono', monospace;
-    font-size: 0.72rem;
-    color: var(--muted);
-    padding: 6px 12px;
-    background: var(--panel);
-    border: 1px solid var(--border);
-    border-radius: 6px;
-    display: flex;
-    gap: 16px;
-  }
-  .info-bar span.ok  { color: var(--green); }
-  .info-bar span.bad { color: var(--red); }
+  *{box-sizing:border-box;margin:0;padding:0}
+  body{background:var(--bg);color:var(--text);font-family:'Syne',sans-serif;min-height:100vh;display:grid;grid-template-rows:auto 1fr auto}
+  header{padding:28px 48px 20px;border-bottom:1px solid var(--border);display:flex;align-items:center;gap:16px;flex-wrap:wrap}
+  header h1{font-size:1.5rem;font-weight:800;letter-spacing:-.03em}
+  header h1 span{color:var(--cyan)}
+  .badge{font-family:'JetBrains Mono',monospace;font-size:.7rem;background:var(--cyan)22;color:var(--cyan);border:1px solid var(--cyan)44;padding:3px 10px;border-radius:99px}
+  .links{margin-left:auto;display:flex;gap:12px}
+  .links a{font-size:.8rem;color:var(--muted);text-decoration:none;transition:color .2s}
+  .links a:hover{color:var(--cyan)}
+  main{display:grid;grid-template-columns:1fr 1fr;gap:0}
+  .pane{padding:28px 36px;display:flex;flex-direction:column;gap:14px}
+  .pane+.pane{border-left:1px solid var(--border)}
+  .pane-label{font-size:.7rem;font-weight:700;letter-spacing:.12em;text-transform:uppercase;color:var(--muted);display:flex;align-items:center;gap:8px}
+  .dot{width:8px;height:8px;border-radius:50%}
+  .dot-cyan{background:var(--cyan)}.dot-green{background:var(--green)}
+  /* format tabs */
+  .format-tabs{display:flex;gap:6px;border-bottom:1px solid var(--border);padding-bottom:10px}
+  .tab{background:transparent;border:1px solid var(--border);color:var(--muted);padding:5px 14px;border-radius:6px;font-family:'JetBrains Mono',monospace;font-size:.72rem;cursor:pointer;transition:all .2s;text-transform:uppercase;letter-spacing:.06em}
+  .tab.active{border-color:var(--cyan);color:var(--cyan);background:var(--cyan)11}
+  .tab:hover:not(.active){border-color:var(--border);color:var(--text)}
+  textarea,#output{flex:1;min-height:320px;font-family:'JetBrains Mono',monospace;font-size:.8rem;line-height:1.75;background:var(--panel);border:1px solid var(--border);border-radius:var(--radius);padding:18px;color:var(--text);resize:none;outline:none;transition:border-color .2s}
+  textarea:focus{border-color:var(--cyan)66}
+  #output{white-space:pre-wrap;overflow-y:auto;color:#c0c0e0}
+  #output.placeholder{color:var(--muted);font-style:italic}
+  #output.loading{color:var(--cyan);animation:pulse 1s ease-in-out infinite}
+  #output.error{color:var(--red)}
+  @keyframes pulse{0%,100%{opacity:1}50%{opacity:.45}}
+  .controls{display:flex;flex-wrap:wrap;gap:10px;align-items:center}
+  select{background:var(--panel);border:1px solid var(--border);color:var(--text);padding:8px 12px;border-radius:8px;font-family:'Syne',sans-serif;font-size:.8rem;outline:none;cursor:pointer;transition:border-color .2s}
+  select:hover{border-color:var(--cyan)55}
+  #run-btn{margin-left:auto;background:var(--cyan);color:#000;border:none;padding:10px 28px;border-radius:8px;font-family:'Syne',sans-serif;font-weight:700;font-size:.85rem;cursor:pointer;transition:transform .15s,opacity .15s;letter-spacing:.04em}
+  #run-btn:hover{opacity:.9;transform:translateY(-1px)}
+  #run-btn:active{transform:translateY(0)}
+  #run-btn:disabled{opacity:.5;cursor:not-allowed;transform:none}
+  .samples{display:flex;gap:6px;flex-wrap:wrap;align-items:center}
+  .sample-btn{background:transparent;border:1px solid var(--border);color:var(--muted);padding:4px 10px;border-radius:5px;font-family:'JetBrains Mono',monospace;font-size:.7rem;cursor:pointer;transition:all .2s}
+  .sample-btn:hover{border-color:var(--cyan)66;color:var(--cyan)}
+  .info-bar{font-family:'JetBrains Mono',monospace;font-size:.72rem;color:var(--muted);padding:6px 12px;background:var(--panel);border:1px solid var(--border);border-radius:6px;display:flex;gap:14px;flex-wrap:wrap}
+  .info-bar .ok{color:var(--green)}.info-bar .bad{color:var(--red)}.info-bar .hi{color:var(--cyan)}
+  footer{padding:14px 48px;border-top:1px solid var(--border);font-size:.72rem;color:var(--muted);display:flex;justify-content:space-between}
+  footer a{color:var(--muted);text-decoration:none}.footer a:hover{color:var(--cyan)}
+  .copy-btn{background:transparent;border:1px solid var(--border);color:var(--muted);padding:4px 10px;border-radius:5px;font-family:'JetBrains Mono',monospace;font-size:.7rem;cursor:pointer;transition:all .2s;margin-left:auto}
+  .copy-btn:hover{border-color:var(--green)66;color:var(--green)}
 </style>
 </head>
 <body>
@@ -198,72 +67,72 @@
   <div class="links">
     <a href="https://github.com/AceAnomDev/json-humanized" target="_blank">GitHub</a>
     <a href="https://www.npmjs.com/package/json-humanized" target="_blank">npm</a>
-    <a href="https://github.com/AceAnomDev/json-humanized#readme" target="_blank">Docs</a>
   </div>
 </header>
 
 <main>
-  <!-- LEFT: input -->
+  <!-- INPUT -->
   <div class="pane">
-    <div class="pane-label"><span class="dot dot-cyan"></span>JSON / YAML / TOML Input</div>
+    <div class="pane-label"><span class="dot dot-cyan"></span>Input</div>
+
+    <!-- format tabs -->
+    <div class="format-tabs">
+      <button class="tab active" onclick="switchInputFormat('json')">JSON</button>
+      <button class="tab"        onclick="switchInputFormat('yaml')">YAML</button>
+      <button class="tab"        onclick="switchInputFormat('toml')">TOML</button>
+    </div>
 
     <div class="samples">
-      <span style="font-size:.72rem;color:var(--muted);margin-right:4px">Examples:</span>
-      <button class="sample-btn" onclick="loadSample('user')">user profile</button>
-      <button class="sample-btn" onclick="loadSample('api')">api response</button>
+      <span style="font-size:.7rem;color:var(--muted)">Examples:</span>
+      <button class="sample-btn" onclick="loadSample('user')">user</button>
+      <button class="sample-btn" onclick="loadSample('api')">api</button>
       <button class="sample-btn" onclick="loadSample('error')">error</button>
-      <button class="sample-btn" onclick="loadSample('array')">list</button>
+      <button class="sample-btn" onclick="loadSample('list')">list</button>
     </div>
 
-    <textarea id="input" spellcheck="false" placeholder='Paste JSON, YAML, or TOML here…
-
-{
-  "name": "Alice",
-  "age": 30
-}'></textarea>
+    <textarea id="input" spellcheck="false" placeholder="Paste JSON, YAML, or TOML here…"></textarea>
 
     <div class="controls">
-      <select id="sel-engine">
-        <option value="local">⚡ local (offline)</option>
-        <option value="ai">🤖 ai (Claude API)</option>
-      </select>
       <select id="sel-format">
         <option value="plain">plain</option>
         <option value="markdown">markdown</option>
         <option value="story">story</option>
-        <option value="json">json</option>
       </select>
       <select id="sel-mode">
         <option value="structured">structured</option>
         <option value="prose">prose</option>
-        <option value="story">story</option>
       </select>
+      <span style="font-size:.72rem;color:var(--muted);font-family:'JetBrains Mono',monospace">Ctrl+↵</span>
       <button id="run-btn" onclick="run()">Humanize →</button>
     </div>
   </div>
 
-  <!-- RIGHT: output -->
+  <!-- OUTPUT -->
   <div class="pane">
-    <div class="pane-label"><span class="dot dot-green"></span>Human-Readable Output</div>
+    <div class="pane-label">
+      <span class="dot dot-green"></span>Output
+      <button class="copy-btn" onclick="copyOutput()">copy</button>
+    </div>
     <div id="output" class="placeholder">Your output will appear here…</div>
-    <div class="info-bar" id="info-bar">
-      <span id="stat-chars">chars: —</span>
-      <span id="stat-keys">keys: —</span>
-      <span id="stat-engine">engine: —</span>
-      <span id="stat-time">time: —</span>
+    <div class="info-bar">
+      <span id="s-fmt">format: —</span>
+      <span id="s-type">type: —</span>
+      <span id="s-keys">fields: —</span>
+      <span id="s-time">time: —</span>
     </div>
   </div>
 </main>
 
 <footer>
-  <span>json-humanized · MIT license</span>
-  <span><a href="https://github.com/AceAnomDev/json-humanized/issues" target="_blank">Report an issue</a></span>
+  <span>json-humanized · MIT</span>
+  <span><a href="https://github.com/AceAnomDev/json-humanized/issues" target="_blank">Report issue</a></span>
 </footer>
 
 <script>
-// ── samples ──────────────────────────────────────────────────────────────────
+// ── samples per format ────────────────────────────────────────────────────────
 const SAMPLES = {
-  user: `{
+  json: {
+    user: `{
   "id": "usr_8f3k2",
   "name": "Alice Johnson",
   "email": "alice@example.com",
@@ -272,31 +141,21 @@ const SAMPLES = {
   "created_at": "2024-03-15T10:30:00Z",
   "balance": 4250.75,
   "is_active": true,
-  "address": {
-    "city": "San Francisco",
-    "country": "US",
-    "zip": "94105"
-  },
+  "address": { "city": "San Francisco", "country": "US" },
   "tags": ["premium", "early-adopter"]
 }`,
-  api: `{
+    api: `{
   "data": {
     "results": [
-      { "id": 1, "title": "Introduction to AI", "score": 9.2 },
-      { "id": 2, "title": "Machine Learning 101", "score": 8.7 }
+      { "id": 1, "title": "Intro to AI", "score": 9.2 },
+      { "id": 2, "title": "ML 101",      "score": 8.7 }
     ],
     "total": 42
   },
-  "meta": {
-    "page": 1,
-    "per_page": 2,
-    "took_ms": 34
-  },
-  "links": {
-    "next": "/api/v1/courses?page=2"
-  }
+  "meta": { "page": 1, "per_page": 2, "took_ms": 34 },
+  "links": { "next": "/api/v1/courses?page=2" }
 }`,
-  error: `{
+    error: `{
   "error": {
     "code": 422,
     "message": "Validation failed",
@@ -307,73 +166,308 @@ const SAMPLES = {
   },
   "request_id": "req_7fh2k"
 }`,
-  array: `[
+    list: `[
   { "user_id": "u1", "name": "Bob",   "score": 98, "country": "UK" },
   { "user_id": "u2", "name": "Carol", "score": 87, "country": "DE" },
   { "user_id": "u3", "name": "Dave",  "score": 73, "country": "US" }
 ]`,
+  },
+
+  yaml: {
+    user: `id: usr_8f3k2
+name: Alice Johnson
+email: alice@example.com
+age: 28
+password: hunter2
+created_at: "2024-03-15T10:30:00Z"
+balance: 4250.75
+is_active: true
+address:
+  city: San Francisco
+  country: US
+tags:
+  - premium
+  - early-adopter`,
+    api: `data:
+  results:
+    - id: 1
+      title: Intro to AI
+      score: 9.2
+    - id: 2
+      title: ML 101
+      score: 8.7
+  total: 42
+meta:
+  page: 1
+  per_page: 2
+  took_ms: 34
+links:
+  next: /api/v1/courses?page=2`,
+    error: `error:
+  code: 422
+  message: Validation failed
+  details:
+    - field: email
+      reason: Invalid email format
+    - field: age
+      reason: Must be between 18 and 120
+request_id: req_7fh2k`,
+    list: `- user_id: u1
+  name: Bob
+  score: 98
+  country: UK
+- user_id: u2
+  name: Carol
+  score: 87
+  country: DE
+- user_id: u3
+  name: Dave
+  score: 73
+  country: US`,
+  },
+
+  toml: {
+    user: `id = "usr_8f3k2"
+name = "Alice Johnson"
+email = "alice@example.com"
+age = 28
+password = "hunter2"
+created_at = "2024-03-15T10:30:00Z"
+balance = 4250.75
+is_active = true
+tags = ["premium", "early-adopter"]
+
+[address]
+city = "San Francisco"
+country = "US"`,
+    api: `[meta]
+page = 1
+per_page = 2
+took_ms = 34
+
+[links]
+next = "/api/v1/courses?page=2"
+
+[[data.results]]
+id = 1
+title = "Intro to AI"
+score = 9.2
+
+[[data.results]]
+id = 2
+title = "ML 101"
+score = 8.7`,
+    error: `request_id = "req_7fh2k"
+
+[error]
+code = 422
+message = "Validation failed"
+
+[[error.details]]
+field = "email"
+reason = "Invalid email format"
+
+[[error.details]]
+field = "age"
+reason = "Must be between 18 and 120"`,
+    list: `[[items]]
+user_id = "u1"
+name = "Bob"
+score = 98
+country = "UK"
+
+[[items]]
+user_id = "u2"
+name = "Carol"
+score = 87
+country = "DE"
+
+[[items]]
+user_id = "u3"
+name = "Dave"
+score = 73
+country = "US"`,
+  },
 };
 
+// ── minimal inline TOML parser ─────────────────────────────────────────────
+// Handles the common subset: key = value, [section], [[array]]
+function parseTOML(text) {
+  const root   = {};
+  let   cur    = root;
+  let   arrKey = null;
+  let   arrRef = null;
+
+  const lines = text.split('\n');
+  for (let raw of lines) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+
+    // [[array of tables]]
+    const arrMatch = line.match(/^\[\[(.+)\]\]$/);
+    if (arrMatch) {
+      const parts = arrMatch[1].trim().split('.');
+      let obj = root;
+      for (let i = 0; i < parts.length - 1; i++) {
+        if (!obj[parts[i]]) obj[parts[i]] = {};
+        obj = obj[parts[i]];
+      }
+      const last = parts[parts.length - 1];
+      if (!Array.isArray(obj[last])) obj[last] = [];
+      const newEntry = {};
+      obj[last].push(newEntry);
+      cur = newEntry;
+      arrKey = null;
+      continue;
+    }
+
+    // [section]
+    const secMatch = line.match(/^\[(.+)\]$/);
+    if (secMatch) {
+      const parts = secMatch[1].trim().split('.');
+      cur = root;
+      for (const p of parts) {
+        if (!cur[p]) cur[p] = {};
+        cur = cur[p];
+      }
+      arrKey = null;
+      continue;
+    }
+
+    // key = value
+    const eqIdx = line.indexOf('=');
+    if (eqIdx < 0) continue;
+    const key = line.slice(0, eqIdx).trim();
+    const val = line.slice(eqIdx + 1).trim();
+    cur[key] = parseTOMLValue(val);
+  }
+  return root;
+}
+
+function parseTOMLValue(val) {
+  if (val === 'true')  return true;
+  if (val === 'false') return false;
+  if (/^-?\d+\.\d+$/.test(val)) return parseFloat(val);
+  if (/^-?\d+$/.test(val))      return parseInt(val, 10);
+  if (val.startsWith('"') && val.endsWith('"'))   return val.slice(1,-1).replace(/\\n/g,'\n').replace(/\\t/g,'\t');
+  if (val.startsWith("'") && val.endsWith("'"))   return val.slice(1,-1);
+  if (val.startsWith('[') && val.endsWith(']')) {
+    const inner = val.slice(1,-1).trim();
+    if (!inner) return [];
+    return inner.split(',').map(s => parseTOMLValue(s.trim()));
+  }
+  return val;
+}
+
+// ── state ────────────────────────────────────────────────────────────────────
+let currentFmt = 'json';
+
+function switchInputFormat(fmt) {
+  currentFmt = fmt;
+  document.querySelectorAll('.tab').forEach(t => t.classList.remove('active'));
+  event.target.classList.add('active');
+  loadSample('user'); // reload current sample in new format
+  document.getElementById('output').textContent = 'Your output will appear here…';
+  document.getElementById('output').className = 'placeholder';
+}
+
 function loadSample(key) {
-  document.getElementById('input').value = SAMPLES[key];
+  document.getElementById('input').value = SAMPLES[currentFmt][key] || '';
 }
 
-// ── rule-based local engine (client-side) ───────────────────────────────────
-function humanizeLocal(data, format) {
-  function fmtKey(k) {
-    return k.replace(/([A-Z])/g,' $1').replace(/[_\-]+/g,' ').trim().toLowerCase();
+// ── parse input ──────────────────────────────────────────────────────────────
+function parseInput(text, fmt) {
+  if (fmt === 'yaml') {
+    if (typeof jsyaml === 'undefined') throw new Error('js-yaml failed to load');
+    return jsyaml.load(text);
   }
-  function fmtVal(v, key='') {
-    if (v === null || v === undefined) return 'not specified';
-    if (v === '') return 'empty';
-    const k = (key||'').toLowerCase();
-    if (typeof v === 'boolean') return v ? 'yes' : 'no';
-    if (/(password|secret|token|hash)/i.test(k)) return '*** (hidden)';
-    if (/(created|updated|at)$/i.test(k) && typeof v==='string') {
-      try { return new Date(v).toLocaleString('en-US',{year:'numeric',month:'long',day:'numeric',hour:'2-digit',minute:'2-digit'}); } catch{}
-    }
-    if (/(price|cost|amount|salary|balance)/i.test(k) && typeof v==='number') {
-      return v>=1e6?`$${(v/1e6).toFixed(2)}M`:v>=1e3?`$${(v/1e3).toFixed(1)}K`:`$${v.toFixed(2)}`;
-    }
-    if (/(email)/i.test(k)) return `email address: ${v}`;
-    if (typeof v === 'number') return v.toLocaleString();
-    if (typeof v === 'string' && v.length > 150) return v.slice(0,150)+'… (truncated)';
-    if (Array.isArray(v)) {
-      if (v.length===0) return 'none';
-      if (v.every(x=>typeof x !== 'object')) return v.join(', ');
-      return `${v.length} item(s)`;
-    }
-    if (typeof v === 'object') return `{${Object.keys(v).length} field(s)}`;
-    return String(v);
+  if (fmt === 'toml') {
+    return parseTOML(text);
   }
-  function objLines(obj, depth=0) {
-    const pfx = '  '.repeat(depth);
-    const lines = [];
-    for (const [k,v] of Object.entries(obj)) {
-      const label = fmtKey(k);
-      if (Array.isArray(v) && v.length && typeof v[0]==='object') {
-        lines.push(`${pfx}• ${cap(label)}: ${v.length} entr${v.length===1?'y':'ies'}`);
-        v.slice(0,3).forEach((it,i)=>{
-          lines.push(`${pfx}  [${i+1}] ${objLines(it, depth+2).join(' ')}`);
-        });
-        if (v.length>3) lines.push(`${pfx}  … and ${v.length-3} more`);
-      } else if (v && typeof v==='object' && !Array.isArray(v)) {
-        lines.push(`${pfx}• ${cap(label)}:`);
-        lines.push(...objLines(v, depth+1));
-      } else {
-        lines.push(`${pfx}• ${cap(label)}: ${fmtVal(v,k)}`);
-      }
+  return JSON.parse(text);
+}
+
+// ── humanizer (client-side, mirrors humanizer.js) ────────────────────────────
+function fmtLabel(fmt) {
+  if (fmt === 'yaml') return 'YAML';
+  if (fmt === 'toml') return 'TOML';
+  return 'data';
+}
+
+function detectCtx(k) {
+  k = k.toLowerCase();
+  if (/^(id|uuid|_id)$/.test(k))                       return 'identifier';
+  if (/(password|secret|token|key|hash)/i.test(k))     return 'sensitive';
+  if (/(created|updated|at|date|time)$/i.test(k))      return 'datetime';
+  if (/(email|mail)$/i.test(k))                        return 'email';
+  if (/(price|cost|amount|balance|fee)/i.test(k))      return 'money';
+  if (/(count|qty|total|num)/i.test(k))                return 'count';
+  if (/(age)$/i.test(k))                               return 'age';
+  if (/(rating|score|rank)/i.test(k))                  return 'rating';
+  return 'generic';
+}
+
+function fmtKey(k) {
+  return k.replace(/([A-Z])/g,' $1').replace(/[_\-]+/g,' ').trim().toLowerCase();
+}
+
+function fmtVal(v, key='') {
+  if (v === null || v === undefined) return 'not specified';
+  if (v === '') return 'empty';
+  const ctx = detectCtx(key);
+  if (typeof v === 'boolean') return v ? 'yes' : 'no';
+  if (ctx === 'sensitive') return '*** (hidden)';
+  if (ctx === 'money' && typeof v==='number') {
+    return v>=1e6?`$${(v/1e6).toFixed(2)}M`:v>=1e3?`$${(v/1e3).toFixed(1)}K`:`$${v.toFixed(2)}`;
+  }
+  if (ctx === 'age'    && typeof v==='number') return `${v} year${v!==1?'s':''} old`;
+  if (ctx === 'rating' && typeof v==='number') return `${v}/10`;
+  if (ctx === 'datetime' && typeof v==='string') {
+    try { const d=new Date(v); if(!isNaN(d)) return d.toLocaleString('en-US',{year:'numeric',month:'long',day:'numeric'}); } catch{}
+  }
+  if (ctx === 'email') return `email: ${v}`;
+  if (Array.isArray(v)) {
+    if (!v.length) return 'none';
+    if (v.every(x=>typeof x!=='object')) return v.join(', ');
+    return `${v.length} item(s)`;
+  }
+  if (typeof v==='object') return `{${Object.keys(v).length} field(s)}`;
+  if (typeof v==='number') return v.toLocaleString();
+  if (typeof v==='string' && v.length>150) return v.slice(0,150)+'…';
+  return String(v);
+}
+
+function objLines(obj, depth=0) {
+  const pfx='  '.repeat(depth), lines=[];
+  for (const [k,v] of Object.entries(obj)) {
+    const label = fmtKey(k);
+    if (Array.isArray(v) && v.length && typeof v[0]==='object') {
+      lines.push(`${pfx}• ${cap(label)}: ${v.length} entr${v.length===1?'y':'ies'}`);
+      v.slice(0,3).forEach((it,i) => {
+        lines.push(`${pfx}  [${i+1}] ${objLines(it,0).join(' ').slice(0,120)}`);
+      });
+      if (v.length>3) lines.push(`${pfx}  … and ${v.length-3} more`);
+    } else if (v && typeof v==='object' && !Array.isArray(v)) {
+      lines.push(`${pfx}• ${cap(label)}:`);
+      lines.push(...objLines(v,depth+1));
+    } else {
+      lines.push(`${pfx}• ${cap(label)}: ${fmtVal(v,k)}`);
     }
-    return lines;
   }
-  function cap(s) { return s ? s[0].toUpperCase()+s.slice(1) : ''; }
+  return lines;
+}
+
+function cap(s) { return s?s[0].toUpperCase()+s.slice(1):'' }
 
+function humanizeData(data, fmt, outFmt) {
+  const lbl = fmtLabel(fmt);
   let intro='', body='';
+
   if (Array.isArray(data)) {
-    intro = `This JSON contains a list of ${data.length} record${data.length!==1?'s':''}.`;
+    intro = `This ${lbl} contains a list of ${data.length} record${data.length!==1?'s':''}.`;
     const limit = Math.min(data.length, 10);
     const lines = [];
-    for(let i=0;i<limit;i++) {
+    for(let i=0;i<limit;i++){
       if (typeof data[i]==='object') lines.push(`\nRecord ${i+1}:\n${objLines(data[i],1).join('\n')}`);
       else lines.push(`\nItem ${i+1}: ${fmtVal(data[i])}`);
     }
@@ -381,66 +475,64 @@ function humanizeLocal(data, format) {
     body = lines.join('');
   } else if (data && typeof data==='object') {
     const keys = Object.keys(data);
-    if ('error' in data || 'errors' in data) intro='This JSON describes an error or failure response.';
-    else if ('data' in data && ('meta' in data || 'links' in data)) intro='This JSON is an API response with data and metadata.';
-    else intro=`This JSON contains a structured object with ${keys.length} field${keys.length!==1?'s':''}.`;
+    if ('error' in data || 'errors' in data)
+      intro=`This ${lbl} describes an error or failure response.`;
+    else if ('data' in data && ('meta' in data||'links' in data))
+      intro=`This ${lbl} is an API response with data and metadata.`;
+    else
+      intro=`This ${lbl} contains a structured object with ${keys.length} field${keys.length!==1?'s':''}.`;
     body = '\n' + objLines(data,0).join('\n');
   } else {
-    return `This JSON contains a single ${typeof data} value: ${data}`;
+    return `This ${lbl} contains a single value: ${data}`;
   }
 
   const text = `${intro}\n${body}`;
 
-  if (format === 'markdown') {
-    return `# JSON Analysis\n\n## Summary\n\n${text}\n\n---\n*Processed by json-humanized (local engine)*`;
-  }
-  if (format === 'story') {
-    return `${'━'.repeat(50)}\n  📖  THE DATA STORY\n${'━'.repeat(50)}\n\n${text}\n\n${'━'.repeat(50)}`;
+  if (outFmt==='markdown') {
+    return `# ${lbl.toUpperCase()} Analysis\n\n## Summary\n\n${text}\n\n---\n*Processed by json-humanized (local engine)*`;
   }
-  if (format === 'json') {
-    return JSON.stringify({ humanized: text, metadata: { engine: 'local', timestamp: new Date().toISOString() }}, null, 2);
+  if (outFmt==='story') {
+    return `${'━'.repeat(52)}\n  📖  THE ${lbl.toUpperCase()} STORY\n${'━'.repeat(52)}\n\n${text}\n\n${'━'.repeat(52)}`;
   }
-  return `${text}\n\n[Processed by: local]`;
+  return text;
 }
 
 // ── run ──────────────────────────────────────────────────────────────────────
 async function run() {
   const raw    = document.getElementById('input').value.trim();
-  const engine = document.getElementById('sel-engine').value;
-  const format = document.getElementById('sel-format').value;
+  const outFmt = document.getElementById('sel-format').value;
   const out    = document.getElementById('output');
   const btn    = document.getElementById('run-btn');
 
-  if (!raw) { out.textContent='⚠ Paste some JSON first'; out.className='error'; return; }
+  if (!raw) { out.textContent='⚠  Paste some input first'; out.className='error'; return; }
 
   let data;
-  try { data = JSON.parse(raw); }
-  catch { out.textContent='✖ Invalid JSON — please check your input'; out.className='error'; return; }
-
-  // update info bar
-  const chars = raw.length;
-  const keys  = Array.isArray(data) ? data.length : typeof data==='object' ? Object.keys(data).length : 1;
-  document.getElementById('stat-chars').textContent = `chars: ${chars}`;
-  document.getElementById('stat-keys').textContent  = Array.isArray(data) ? `items: ${keys}` : `keys: ${keys}`;
-  document.getElementById('stat-engine').textContent = `engine: ${engine}`;
-
-  if (engine === 'ai') {
-    out.textContent = '⚠  AI mode is not available in the browser demo.\n\nInstall the CLI and use:\n  jh data.json --engine ai';
+  try {
+    data = parseInput(raw, currentFmt);
+  } catch(e) {
+    out.textContent = `✖ Invalid ${currentFmt.toUpperCase()}: ${e.message}`;
     out.className = 'error';
     return;
   }
 
+  // info bar
+  const keys = Array.isArray(data)?data.length:typeof data==='object'?Object.keys(data).length:1;
+  document.getElementById('s-fmt').innerHTML   = `format: <span class="hi">${currentFmt.toUpperCase()}</span>`;
+  document.getElementById('s-type').textContent = `type: ${Array.isArray(data)?'array':typeof data}`;
+  document.getElementById('s-keys').textContent = Array.isArray(data)?`items: ${keys}`:`fields: ${keys}`;
+
   btn.disabled = true;
   out.className = 'loading';
   out.textContent = 'Humanizing…';
   const t0 = performance.now();
 
   try {
-    const result = humanizeLocal(data, format);
-    const ms = (performance.now() - t0).toFixed(0);
+    await new Promise(r => setTimeout(r, 40)); // let spinner render
+    const result = humanizeData(data, currentFmt, outFmt);
+    const ms = (performance.now()-t0).toFixed(0);
     out.textContent = result;
     out.className = '';
-    document.getElementById('stat-time').innerHTML = `time: <span class="ok">${ms}ms</span>`;
+    document.getElementById('s-time').innerHTML = `time: <span class="ok">${ms}ms</span>`;
   } catch(e) {
     out.textContent = '✖ ' + e.message;
     out.className = 'error';
@@ -449,12 +541,17 @@ async function run() {
   }
 }
 
-// Auto-run on Ctrl+Enter
+function copyOutput() {
+  const txt = document.getElementById('output').textContent;
+  if (!txt || document.getElementById('output').classList.contains('placeholder')) return;
+  navigator.clipboard.writeText(txt).catch(()=>{});
+}
+
 document.addEventListener('keydown', e => {
-  if ((e.ctrlKey || e.metaKey) && e.key === 'Enter') run();
+  if ((e.ctrlKey||e.metaKey) && e.key==='Enter') run();
 });
 
-// Load user sample on start
+// init
 loadSample('user');
 </script>
 </body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "json-humanized",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Transform any JSON/YAML/TOML into human-readable prose — powered by Claude AI, OpenAI, Ollama, or built-in rule-based engine",
   "main": "src/index.js",
   "types": "index.d.ts",
@@ -39,14 +39,14 @@
   "dependencies": {
     "chalk": "4.1.2",
     "commander": "11.1.0",
-    "ora": "5.4.1"
+    "ora": "5.4.1",
+    "js-yaml": "^4.1.0",
+    "@iarna/toml": "^2.2.5"
   },
   "optionalDependencies": {
     "@anthropic-ai/sdk": "^0.20.0",
-    "openai": "^4.0.0",
-    "js-yaml": "^4.1.0",
-    "@iarna/toml": "^2.2.5",
-    "handlebars": "^4.7.8"
+    "handlebars": "^4.7.8",
+    "openai": "^4.0.0"
   },
   "engines": {
     "node": ">=14.0.0"

package/src/formatters/index.js

@@ -4,9 +4,19 @@
 //  json-humanized · Output formatters
 // ─────────────────────────────────────────────────────────────────────────────
 
-/**
- * Plain text formatter (default)
- */
+/** Derive a readable label from sourceFormat option or filename extension */
+function sourceLabel(meta = {}) {
+  const sf = (meta.sourceFormat || '').toLowerCase();
+  if (sf === 'yaml' || sf === 'yml') return 'YAML';
+  if (sf === 'toml')                 return 'TOML';
+  if (sf === 'json')                 return 'JSON';
+  const ext = (meta.filename || '').split('.').pop().toLowerCase();
+  if (ext === 'yaml' || ext === 'yml') return 'YAML';
+  if (ext === 'toml')                  return 'TOML';
+  if (ext === 'json')                  return 'JSON';
+  return 'Data';
+}
+
 function formatPlain(text, meta = {}) {
   const lines = [];
   if (meta.filename) {
@@ -21,19 +31,14 @@ function formatPlain(text, meta = {}) {
   return lines.join('\n');
 }
 
-/**
- * Markdown formatter
- */
 function formatMarkdown(text, meta = {}) {
+  const lbl   = sourceLabel(meta);
   const lines = [];
 
-  if (meta.filename) {
-    lines.push(`# JSON Analysis: \`${meta.filename}\``);
-    lines.push('');
-  } else {
-    lines.push('# JSON Analysis');
-    lines.push('');
-  }
+  lines.push(meta.filename
+    ? `# ${lbl} Analysis: \`${meta.filename}\``
+    : `# ${lbl} Analysis`);
+  lines.push('');
 
   if (meta.timestamp) {
     lines.push(`> Generated on ${new Date(meta.timestamp).toLocaleString()}`);
@@ -64,43 +69,32 @@ function formatMarkdown(text, meta = {}) {
   return lines.join('\n');
 }
 
-/**
- * Story/narrative formatter — wraps output in a storytelling frame
- */
 function formatStory(text, meta = {}) {
+  const lbl   = sourceLabel(meta);
   const lines = [];
   lines.push('━'.repeat(60));
-  lines.push('  📖  THE DATA STORY');
+  lines.push(`  📖  THE ${lbl.toUpperCase()} STORY`);
   lines.push('━'.repeat(60));
   lines.push('');
   lines.push(text);
   lines.push('');
   lines.push('━'.repeat(60));
-  if (meta.filename) {
-    lines.push(`  Source: ${meta.filename}`);
-  }
+  if (meta.filename) lines.push(`  Source: ${meta.filename}`);
   return lines.join('\n');
 }
 
-/**
- * JSON formatter — outputs structured metadata alongside the description
- */
 function formatJSON(text, meta = {}) {
-  const output = {
+  return JSON.stringify({
     humanized: text,
     metadata: {
-      engine: meta.engine || 'local',
-      filename: meta.filename || null,
+      engine:    meta.engine    || 'local',
+      filename:  meta.filename  || null,
       timestamp: meta.timestamp || new Date().toISOString(),
-      stats: meta.stats || {},
+      stats:     meta.stats     || {},
     },
-  };
-  return JSON.stringify(output, null, 2);
+  }, null, 2);
 }
 
-/**
- * Apply a named formatter
- */
 function applyFormat(text, format = 'plain', meta = {}) {
   switch (format) {
     case 'markdown': return formatMarkdown(text, meta);

package/src/humanizer.js

@@ -14,12 +14,8 @@ const TYPE_LABELS = {
   null:    'empty value',
 };
 
-/**
- * Detect semantic meaning from a key name
- */
 function detectKeyContext(key) {
   const k = key.toLowerCase();
-
   if (/^(id|uuid|guid|_id)$/.test(k))          return 'identifier';
   if (/(_id|Id)$/.test(key))                    return 'reference';
   if (/(created|updated|modified|timestamp|date|time|at)$/i.test(k)) return 'datetime';
@@ -42,30 +38,23 @@ function detectKeyContext(key) {
   if (/(address|city|country|region|zip|postal)/i.test(k)) return 'location';
   if (/(rating|score|rank)/i.test(k))           return 'rating';
   if (/(error|err|exception|message|msg)/i.test(k)) return 'error';
-
   return 'generic';
 }
 
-/**
- * Format a key name into natural English label
- */
 function humanizeKey(key) {
   return key
-    .replace(/([A-Z])/g, ' $1')          // camelCase → spaced
-    .replace(/[_\-\.]+/g, ' ')           // snake_case / kebab-case → spaced
+    .replace(/([A-Z])/g, ' $1')
+    .replace(/[_\-\.]+/g, ' ')
     .replace(/\s+/g, ' ')
     .trim()
     .toLowerCase();
 }
 
-/**
- * Format a value with contextual awareness
- */
 function humanizeValue(value, key = '', depth = 0) {
   if (value === null || value === undefined) return 'not specified';
   if (value === '') return 'empty';
 
-  const ctx = detectKeyContext(key);
+  const ctx  = detectKeyContext(key);
   const type = typeof value;
 
   if (type === 'boolean') {
@@ -98,13 +87,8 @@ function humanizeValue(value, key = '', depth = 0) {
     return value;
   }
 
-  if (Array.isArray(value)) {
-    return humanizeArray(value, key, depth);
-  }
-
-  if (type === 'object') {
-    return humanizeObject(value, depth + 1);
-  }
+  if (Array.isArray(value)) return humanizeArray(value, key, depth);
+  if (type === 'object')    return humanizeObject(value, depth + 1);
 
   return String(value);
 }
@@ -128,17 +112,13 @@ function formatDatetime(str) {
   }
 }
 
-/**
- * Humanize an array value
- */
 function humanizeArray(arr, key = '', depth = 0) {
   if (arr.length === 0) return 'an empty list';
 
-  const itemType = typeof arr[0];
+  const itemType    = typeof arr[0];
   const allSameType = arr.every(i => typeof i === itemType);
-  const label = humanizeKey(key) || 'items';
+  const label       = humanizeKey(key) || 'items';
 
-  // Simple scalar arrays → inline sentence
   if (allSameType && ['string', 'number', 'boolean'].includes(itemType) && arr.length <= 8) {
     const formatted = arr.map(v => humanizeValue(v, '', depth));
     if (formatted.length === 1) return formatted[0];
@@ -146,20 +126,16 @@ function humanizeArray(arr, key = '', depth = 0) {
     return `${formatted.join(', ')} and ${last}`;
   }
 
-  // Complex arrays → count + describe first element
   const preview = humanizeValue(arr[0], '', depth + 1);
   return `a collection of ${arr.length} ${label} (e.g. ${preview}${arr.length > 1 ? ', and more' : ''})`;
 }
 
-/**
- * Humanize an object recursively, returns array of sentences
- */
 function humanizeObject(obj, depth = 0) {
   const entries = Object.entries(obj).filter(([, v]) => v !== undefined);
   if (entries.length === 0) return 'an empty object';
 
   const sentences = [];
-  const indent = '  '.repeat(depth);
+  const indent    = '  '.repeat(depth);
 
   for (const [key, value] of entries) {
     const label = humanizeKey(key);
@@ -174,20 +150,16 @@ function humanizeObject(obj, depth = 0) {
         sentences.push(`${indent}• ${capitalize(label)}: ${value.length} entr${value.length === 1 ? 'y' : 'ies'}`);
         value.slice(0, 5).forEach((item, i) => {
           if (typeof item === 'object' && item !== null) {
-            const sub = humanizeObject(item, depth + 1);
-            sentences.push(`${indent}  [${i + 1}] ${sub}`);
+            sentences.push(`${indent}  [${i + 1}] ${humanizeObject(item, depth + 1)}`);
           } else {
             sentences.push(`${indent}  [${i + 1}] ${humanizeValue(item, '', depth + 1)}`);
           }
         });
-        if (value.length > 5) {
-          sentences.push(`${indent}  … and ${value.length - 5} more`);
-        }
+        if (value.length > 5) sentences.push(`${indent}  … and ${value.length - 5} more`);
       }
     } else if (typeof value === 'object' && value !== null) {
       sentences.push(`${indent}• ${capitalize(label)}:`);
-      const sub = humanizeObject(value, depth + 1);
-      sentences.push(sub);
+      sentences.push(humanizeObject(value, depth + 1));
     } else {
       const hval = humanizeValue(value, key, depth);
       if (ctx === 'identifier') {
@@ -213,70 +185,86 @@ function capitalize(str) {
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
-//  Top-level entry point
+//  Top-level shape detection
 // ─────────────────────────────────────────────────────────────────────────────
 
-/**
- * Detect what kind of structure this JSON represents
- */
 function detectTopLevelShape(data) {
   if (Array.isArray(data)) {
     if (data.length === 0) return { shape: 'empty-array' };
-    const first = data[0];
-    if (typeof first === 'object' && first !== null) return { shape: 'record-list', count: data.length };
+    if (typeof data[0] === 'object' && data[0] !== null)
+      return { shape: 'record-list', count: data.length };
     return { shape: 'scalar-list', count: data.length };
   }
   if (typeof data === 'object' && data !== null) {
     const keys = Object.keys(data);
-    // Detect common API shapes
-    if ('data' in data && ('meta' in data || 'links' in data || 'pagination' in data)) return { shape: 'api-response' };
-    if ('error' in data || 'errors' in data || 'message' in data && 'code' in data) return { shape: 'error-response' };
-    if ('users' in data || 'items' in data || 'results' in data || 'records' in data) return { shape: 'collection' };
-    if (keys.length <= 2) return { shape: 'simple-object' };
+    if ('data' in data && ('meta' in data || 'links' in data || 'pagination' in data))
+      return { shape: 'api-response' };
+    if ('error' in data || 'errors' in data || ('message' in data && 'code' in data))
+      return { shape: 'error-response' };
+    if ('users' in data || 'items' in data || 'results' in data || 'records' in data)
+      return { shape: 'collection' };
+    if (keys.length <= 2)
+      return { shape: 'simple-object' };
     return { shape: 'complex-object', keys: keys.length };
   }
   return { shape: 'primitive' };
 }
 
 /**
- * Build a natural-language introduction for the top-level shape
+ * Returns a format label for use in intro sentences.
+ * @param {'json'|'yaml'|'toml'|string} [sourceFormat]
  */
-function buildIntro(data, shape) {
+function formatLabel(sourceFormat) {
+  switch ((sourceFormat || 'json').toLowerCase()) {
+    case 'yaml': case 'yml': return 'YAML';
+    case 'toml':             return 'TOML';
+    default:                 return 'data';
+  }
+}
+
+function buildIntro(data, shape, sourceFormat) {
+  const lbl = formatLabel(sourceFormat);
+
   switch (shape.shape) {
     case 'empty-array':
-      return 'This JSON contains an empty list with no items.';
+      return `This ${lbl} contains an empty list with no items.`;
     case 'record-list':
-      return `This JSON contains a list of ${shape.count} record${shape.count !== 1 ? 's' : ''}.`;
+      return `This ${lbl} contains a list of ${shape.count} record${shape.count !== 1 ? 's' : ''}.`;
     case 'scalar-list':
-      return `This JSON contains a list of ${shape.count} value${shape.count !== 1 ? 's' : ''}.`;
+      return `This ${lbl} contains a list of ${shape.count} value${shape.count !== 1 ? 's' : ''}.`;
     case 'api-response':
-      return 'This JSON is an API response with data and metadata.';
+      return `This ${lbl} is an API response with data and metadata.`;
     case 'error-response':
-      return 'This JSON describes an error or failure response.';
+      return `This ${lbl} describes an error or failure response.`;
     case 'collection':
-      return 'This JSON contains a collection of resources.';
+      return `This ${lbl} contains a collection of resources.`;
     case 'simple-object':
-      return 'This JSON contains a simple object with a few fields.';
+      return `This ${lbl} contains a simple object with a few fields.`;
     case 'complex-object':
-      return `This JSON contains a structured object with ${shape.keys} fields.`;
+      return `This ${lbl} contains a structured object with ${shape.keys} fields.`;
     case 'primitive':
-      return `This JSON contains a single value: ${String(data)}.`;
+      return `This ${lbl} contains a single value: ${String(data)}.`;
     default:
-      return 'This JSON contains the following data:';
+      return `This ${lbl} contains the following data:`;
   }
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+//  Main export
+// ─────────────────────────────────────────────────────────────────────────────
+
 /**
- * Generate a human-readable summary using the rule-based engine
+ * @param {any}    data
+ * @param {object} [options]
+ * @param {string} [options.mode='structured']
+ * @param {string} [options.sourceFormat]  'json' | 'yaml' | 'toml'
  */
 function humanizeLocal(data, options = {}) {
-  const { mode = 'structured', maxDepth = 10 } = options;
+  const { mode = 'structured', sourceFormat } = options;
   const shape = detectTopLevelShape(data);
-  const intro = buildIntro(data, shape);
+  const intro = buildIntro(data, shape, sourceFormat);
 
-  if (shape.shape === 'primitive') {
-    return intro;
-  }
+  if (shape.shape === 'primitive') return intro;
 
   let body = '';
 

package/src/index.js

@@ -78,11 +78,13 @@ async function humanize(data, options = {}) {
     cacheTTL   = 3600,
   } = merged;
 
+  const sourceFormat = merged.sourceFormat || null;
+
   const engineFn = async () => {
     if (engine === 'ai') {
       return humanizeWithAI(data, { apiKey, aiProvider, mode, lang, context, maxChars, ...merged });
     }
-    return humanizeLocal(data, { mode });
+    return humanizeLocal(data, { mode, sourceFormat });
   };
 
   // Use cache only for AI engine (local is instant)
@@ -91,7 +93,7 @@ async function humanize(data, options = {}) {
     : await engineFn();
 
   const stats = computeStats(data);
-  const meta  = { engine, aiProvider, filename, timestamp: new Date().toISOString(), stats, data };
+  const meta  = { engine, aiProvider, filename, sourceFormat, timestamp: new Date().toISOString(), stats, data };
 
   // Template output takes priority over standard formatters
   if (template) {
@@ -119,9 +121,13 @@ async function humanizeFile(filePath, options = {}) {
 
   const data = parseFile(resolved);
 
+  const ext = path.extname(resolved).slice(1).toLowerCase();
+  const sourceFormat = ['yaml', 'yml', 'toml', 'json'].includes(ext) ? ext : undefined;
+
   return humanize(data, {
     ...options,
     filename: options.filename || path.basename(resolved),
+    sourceFormat: options.sourceFormat || sourceFormat,
   });
 }