@kyyinfinite/lumina 1.0.0 → 1.0.2

package/src/parsers/code-tokenizer.js

@@ -1,31 +1,11 @@
-/**
- * @file code-tokenizer.js
- * @module lumina/parsers/code-tokenizer
  *
- * Lightweight hand-rolled lexer for code-block syntax highlighting inside
- * AI Rich Responses. Returns two parallel representations:
  *
- *   - `codeBlock`       — array of `{ codeContent, highlightType }` where
- *                         `highlightType` is the numeric 0-5 enum used by WAProto.
- *   - `unifiedBlocks`   — array of `{ content, type }` with the string label
- *                         (`'DEFAULT' | 'KEYWORD' | 'METHOD' | 'STR' | 'NUMBER' | 'COMMENT'`).
  *
- * The legacy `AIRich.tokenizer` rebuilt its keyword Set on every call and
- * inlined all 660 lines of language maps. Lumina splits the catalog into
- * `code-tokenizer-keywords.js` (built once) and keeps this file focused on
- * the lexer itself (~120 lines).
- */
 
 import { HighlightType, HighlightLabel } from '../proto/enums.js'
 import { KEYWORDS, SLASH_COMMENT_LANGS, HASH_COMMENT_LANGS, BLOCK_COMMENT_LANGS } from './code-tokenizer-keywords.js'
 
-/**
- * @typedef {object} TokenizedCode
- * @property {Array<{ codeContent: string, highlightType: number }>} codeBlock
- * @property {Array<{ content: string, type: string }>} unifiedBlocks
- */
 
-/** Identifier character class per language (CSS & HTML allow `-` / `:`). */
 function identifierChar(lang) {
   switch (lang) {
     case 'css':
@@ -37,19 +17,12 @@ function identifierChar(lang) {
   }
 }
 
-/**
- * Tokenize a code string for syntax highlighting.
  *
- * @param {string} code
- * @param {string} [lang='javascript']   Lower-case language id. Unknown ids degrade gracefully to plain text.
- * @returns {TokenizedCode}
- */
 export function tokenizeCode(code, lang = 'javascript') {
   if (typeof code !== 'string' || code.length === 0) {
     return { codeBlock: [], unifiedBlocks: [] }
   }
 
-  // Plain-text fast-path.
   if (!lang || lang === 'txt' || lang === 'text' || lang === 'plaintext') {
     return {
       codeBlock: [{ codeContent: code, highlightType: HighlightType.DEFAULT }],
@@ -64,12 +37,8 @@ export function tokenizeCode(code, lang = 'javascript') {
   const supportsHashComments = HASH_COMMENT_LANGS.has(lower)
   const supportsBlockComments = BLOCK_COMMENT_LANGS.has(lower)
 
-  /** @type {Array<{ codeContent: string, highlightType: number }>} */
   const tokens = []
 
-  /**
-   * Push a token, merging with the previous one if both share the same type.
-   */
   const push = (content, type) => {
     if (!content) return
     const last = tokens[tokens.length - 1]
@@ -81,7 +50,6 @@ export function tokenizeCode(code, lang = 'javascript') {
   while (i < code.length) {
     const c = code[i]
 
-    // Whitespace.
     if (/\s/.test(c)) {
       const start = i
       while (i < code.length && /\s/.test(code[i])) i++
@@ -89,7 +57,6 @@ export function tokenizeCode(code, lang = 'javascript') {
       continue
     }
 
-    // Block comment: /* ... */
     if (supportsBlockComments && c === '/' && code[i + 1] === '*') {
       const start = i
       i += 2
@@ -99,7 +66,6 @@ export function tokenizeCode(code, lang = 'javascript') {
       continue
     }
 
-    // Slash line comment: //
     if (supportsSlashComments && c === '/' && code[i + 1] === '/') {
       const start = i
       while (i < code.length && code[i] !== '\n') i++
@@ -107,7 +73,6 @@ export function tokenizeCode(code, lang = 'javascript') {
       continue
     }
 
-    // Hash line comment: #  (python, bash, php, rust)
     if (supportsHashComments && c === '#') {
       const start = i
       while (i < code.length && code[i] !== '\n') i++
@@ -115,7 +80,6 @@ export function tokenizeCode(code, lang = 'javascript') {
       continue
     }
 
-    // String literals: ', ", `
     if (c === '"' || c === "'" || c === '`') {
       const start = i
       const quote = c
@@ -131,7 +95,6 @@ export function tokenizeCode(code, lang = 'javascript') {
       continue
     }
 
-    // Numbers.
     if (/[0-9]/.test(c)) {
       const start = i
       while (i < code.length && /[0-9._a-fxA-fX]/.test(code[i])) i++
@@ -139,7 +102,6 @@ export function tokenizeCode(code, lang = 'javascript') {
       continue
     }
 
-    // Identifiers & keywords.
     if (/[a-zA-Z_$]/.test(c)) {
       const start = i
       while (i < code.length && isIdent.test(code[i])) i++
@@ -150,12 +112,10 @@ export function tokenizeCode(code, lang = 'javascript') {
       if (keywords.has(word)) {
         type = HighlightType.KEYWORD
       } else if (lower === 'css') {
-        // Property name? next non-space char is ':'.
         let j = i
         while (j < code.length && /\s/.test(code[j])) j++
         if (code[j] === ':') type = HighlightType.KEYWORD
       } else if (lower === 'html') {
-        // Tag name? previous non-space char is '<' or '</'.
         let p = start - 1
         while (p >= 0 && /\s/.test(code[p])) p--
         if (code[p] === '<' || (code[p] === '/' && code[p - 1] === '<')) {
@@ -163,7 +123,6 @@ export function tokenizeCode(code, lang = 'javascript') {
         }
       }
 
-      // Function call? Next non-space char is '('.
       if (type === HighlightType.DEFAULT) {
         let j = i
         while (j < code.length && /\s/.test(code[j])) j++
@@ -174,7 +133,6 @@ export function tokenizeCode(code, lang = 'javascript') {
       continue
     }
 
-    // Everything else: punctuation.
     push(c, HighlightType.DEFAULT)
     i++
   }

package/src/parsers/index.js

@@ -1,10 +1,3 @@
-/**
- * @file parsers/index.js
- * @module lumina/parsers
- *
- * Barrel re-export for the parsers layer.
- */
-
 export { extractInlineEntities } from './inline-entity.js'
 export { tokenizeCode } from './code-tokenizer.js'
 export { toTableMetadata } from './table-metadata.js'

package/src/parsers/inline-entity.js

@@ -1,42 +1,5 @@
-/**
- * @file inline-entity.js
- * @module lumina/parsers/inline-entity
- *
- * extractInlineEntities — parses three markdown-like inline syntaxes inside
- * AI-rich text content and returns the rewritten text plus proto-ready
- * inline-entity metadata.
- *
- * Supported syntaxes:
- *
- *   [text](url)       → hyperlink   (untrusted if `url` starts with `!`)
- *   [](url)           → citation    (renders as a numeric superscript)
- *   [text]<url|w|h|fh|p>   → latex  (math image with dimensions)
- *
- * The rewritten text replaces each `[...]` span with `{{KEY}}...{{/KEY}}`
- * placeholders that WhatsApp's rich-response renderer substitutes back with
- * the entity's interactive UI element.
- *
- * This is the modernised, de-obfuscated successor to the legacy `extractIE`
- * function in `_build-m.js`. Key changes:
- *
- *   1. The `NIXEL_` prefix (obfuscated as `\u004E\u0049\u0058\u0045\u004C_`)
- *      is replaced by the configurable `LUMINA_` prefix.
- *   2. The off-by-one bug on citation keys is fixed: every counter is now
- *      zero-based and keys match `reference_id` consistently.
- *   3. Magic numbers (font_height, padding, default width/height) are pulled
- *      into named constants.
- *   4. The `createIE` switch-by-if is replaced by a typed lookup table.
- *   5. Pure function, no side-effects — easily unit-testable.
- */
-
 import { entityKey } from '../utils/id.js'
 
-/** @typedef {'hyperlink'|'citation'|'latex'} EntityType */
-
-/**
- * Default LaTeX rendering parameters. Sourced from the legacy implementation.
- * Adjust if WhatsApp updates its rendering defaults.
- */
 const LATEX_DEFAULTS = Object.freeze({
   width: 100,
   height: 100,
@@ -44,11 +7,6 @@ const LATEX_DEFAULTS = Object.freeze({
   padding: 15,
 })
 
-/**
- * Per-type metadata shaper. Replaces the legacy `createIE` switch.
- *
- * @type {Record<EntityType, (item: any) => object>}
- */
 const SHAPERS = {
   hyperlink: (item) => ({
     key: item.key,
@@ -86,76 +44,35 @@ const SHAPERS = {
   }),
 }
 
-/**
- * @typedef {object} ExtractOptions
- * @property {boolean} [extract=true]    Master switch — when false, returns the text unchanged.
- * @property {boolean} [hyperlink=true]  Parse `[text](url)` syntax.
- * @property {boolean} [citation=true]   Parse `[](url)` syntax.
- * @property {boolean} [latex=true]      Parse `[text]<url|w|h|fh|p>` syntax.
- * @property {string}  [prefix='LUMINA'] Override the entity-key prefix.
- */
-
-/**
- * @typedef {object} ExtractResult
- * @property {string} text          Rewritten text with `{{KEY}}…{{/KEY}}` placeholders.
- * @property {Array<{ type: EntityType, key: string, [k: string]: any }>} entities
- *           Raw per-entity descriptors (one per matched span).
- * @property {Array<{ key: string, metadata: object }>} metadata
- *           Proto-ready inline-entity metadata, ready to attach to a primitive.
- */
-
-/**
- * Parse inline entities from text.
- *
- * @param {string} text
- * @param {ExtractOptions} [opts]
- * @returns {ExtractResult}
- */
 export function extractInlineEntities(text, opts = {}) {
-  const {
-    extract = true,
-    hyperlink = true,
-    citation = true,
-    latex = true,
-    prefix = 'LUMINA',
-  } = opts
+  const { extract = true, hyperlink = true, citation = true, latex = true } = opts
 
   if (!extract || typeof text !== 'string' || text.length === 0) {
     return { text: text ?? '', entities: [], metadata: [] }
   }
 
-  /** @type {Array<{ type: EntityType, key: string, [k: string]: any }>} */
   const entities = []
-  /** @type {Array<{ key: string, metadata: object }>} */
   const metadata = []
   let rewritten = ''
   let last = 0
   let citationCount = 0
   let hyperlinkCount = 0
   let latexCount = 0
-
-  /** Bracket stack — supports nested brackets inside the link text. */
   const stack = []
 
   for (let i = 0; i < text.length; i++) {
     const ch = text[i]
 
-    // Push `[` (escaped `\[` ignored).
-    if (ch === '[' && text[i - 1] !== '\\') {
-      stack.push(i)
-      continue
-    }
+    if (ch === '[' && text[i - 1] !== '\\') { stack.push(i); continue }
 
-    // `]` only triggers when followed by `(` (link) or `<` (latex).
     if (ch === ']' && (text[i + 1] === '(' || text[i + 1] === '<')) {
       const start = stack.pop()
       if (start == null) continue
 
       const open = text[i + 1]
       const close = open === '(' ? ')' : '>'
-      const type = /** @type {EntityType} */ (open === '(' ? 'hyperlink-or-citation' : 'latex')
+      const type = open === '(' ? 'hyperlink-or-citation' : 'latex'
 
-      // Walk to the matching close, respecting backslash escapes & nesting.
       let end = i + 2
       let depth = 1
       while (end < text.length && depth) {
@@ -163,61 +80,35 @@ export function extractInlineEntities(text, opts = {}) {
         else if (text[end] === close && text[end - 1] !== '\\') depth--
         end++
       }
-      if (depth) continue // unbalanced — skip.
+      if (depth) continue
 
       const raw = text.slice(start + 1, i).trim()
       const url = text.slice(i + 2, end - 1).trim()
-
-      /** @type {{ type: EntityType, key: string, [k: string]: any } | null} */
       let entry = null
 
       if (type === 'latex') {
         if (!latex) continue
-        const [txt = '', width = null, height = null, fontHeight = null, padding = null] =
-          raw.split('|')
+        const [txt = '', width = null, height = null, fontHeight = null, padding = null] = raw.split('|')
         const key = entityKey('LATEX', latexCount++)
-        entry = {
-          type: 'latex',
-          key,
-          text: txt,
-          url,
-          width,
-          height,
-          fontHeight,
-          padding,
-        }
+        entry = { type: 'latex', key, text: txt, url, width, height, fontHeight, padding }
         rewritten += text.slice(last, start) + `{{${key}}}${txt || 'image'}{{/${key}}}`
       } else if (raw) {
         if (!hyperlink) continue
-        // Untrusted link → URL prefixed with `!`.
         const trusted = !url.startsWith('!')
         const cleanUrl = trusted ? url : url.slice(1)
         const key = entityKey('HYPERLINK', hyperlinkCount++)
-        entry = {
-          type: 'hyperlink',
-          key,
-          text: raw,
-          url: cleanUrl,
-          isTrusted: trusted,
-        }
+        entry = { type: 'hyperlink', key, text: raw, url: cleanUrl, isTrusted: trusted }
         rewritten += text.slice(last, start) + `{{${key}}}${cleanUrl}{{/${key}}}`
       } else {
         if (!citation) continue
         const key = entityKey('CITATION', citationCount)
         citationCount++
-        entry = {
-          type: 'citation',
-          key,
-          referenceId: citationCount, // 1-based, matches key index (zero-based +1)
-          text: '',
-          url,
-        }
+        entry = { type: 'citation', key, referenceId: citationCount, text: '', url }
         rewritten += text.slice(last, start) + `{{${key}}}${url}{{/${key}}}`
       }
 
       last = end
       i = end - 1
-
       entities.push(entry)
       const shaped = SHAPERS[entry.type](entry)
       if (shaped) metadata.push(shaped)

package/src/parsers/table-metadata.js

@@ -1,43 +1,13 @@
-/**
- * @file table-metadata.js
- * @module lumina/parsers/table-metadata
- *
- * Convert a 2-D array of strings into the metadata shape WhatsApp expects
- * inside a `richResponseMessage.submessages[].tableMetadata`.
- *
- * The legacy `AIRich.toTableMetadata` always returned `title: ''` with no
- * way to set it. Lumina accepts a `title` option.
- */
-
 import { extractInlineEntities } from './inline-entity.js'
 
-/**
- * @typedef {object} TableMetadata
- * @property {string} title
- * @property {Array<{ items: string[], isHeading?: boolean }>} rows          Submessage metadata.
- * @property {Array<{ is_header: boolean, cells: string[], markdown_cells?: Array<{ text: string, inline_entities?: object[] }> }>} unifiedRows  Section primitive rows.
- */
-
-/**
- * @param {string[][]} table    2-D array of strings. First row is the header.
- * @param {object} [opts]
- * @param {string} [opts.title='']
- * @param {boolean} [opts.hyperlink=true]
- * @param {boolean} [opts.citation=true]
- * @param {boolean} [opts.latex=true]
- * @returns {TableMetadata}
- */
 export function toTableMetadata(table, opts = {}) {
   if (!Array.isArray(table) || !table.every((row) => Array.isArray(row) && row.every((c) => typeof c === 'string'))) {
     throw new TypeError('Table must be a 2-D array of strings')
   }
 
   const { title = '', hyperlink = true, citation = true, latex = true } = opts
-
   const [header, ...rows] = table
   const maxLen = Math.max(header.length, ...rows.map((r) => r.length))
-
-  /** Pad a row to the table's max column count. */
   const normalize = (r) => [...r, ...Array(Math.max(0, maxLen - r.length)).fill('')]
 
   const unifiedRows = [
@@ -50,12 +20,8 @@ export function toTableMetadata(table, opts = {}) {
       if (extracted.metadata.length) out.inline_entities = extracted.metadata
       return out
     })
-
     const hasInline = markdownCells.some((c) => c.inline_entities?.length)
-    return {
-      ...row,
-      ...(hasInline ? { markdown_cells: markdownCells } : {}),
-    }
+    return { ...row, ...(hasInline ? { markdown_cells: markdownCells } : {}) }
   })
 
   const rowsMeta = unifiedRows.map((r) => ({

package/src/proto/enums.js

@@ -1,93 +1,41 @@
-/**
- * @file enums.js
- * @module lumina/proto/enums
- *
- * Single source of truth for every magic number / magic string the WhatsApp
- * protocol expects inside interactive messages, rich responses, and relay
- * nodes. Update the wire format here once, and the whole framework follows.
- *
- * Replaces the 20+ scattered magic values documented in Tahap-1 analysis:
- *   - messageType: 1, 2, 4, 5, 9
- *   - forwardOrigin: 4
- *   - headerType: 0,1,3,4,5,6
- *   - native_flow v: '9'
- *   - botJid: '0@bot'
- *   - 12x __typename string literals
- *   - highlightType: 0-5
- *   - imagine_type: 'IMAGE' | 'ANIMATE'
- *   - etc.
- */
-
-/**
- * Rich-response submessage type. Stored in `richResponseMessage.submessages[].messageType`.
- */
 export const MessageType = Object.freeze({
-  /** Grid-image rich response. */
   RICH_RESPONSE: 1,
-  /** Plain text submessage (also used as fallback for video/product/post). */
   TEXT: 2,
-  /** Table metadata submessage. */
   TABLE: 4,
-  /** Code-block metadata submessage. */
   CODE: 5,
-  /** Reels / contentItems metadata submessage. */
   REELS: 9,
 })
 
-/**
- * `contextInfo.forwardOrigin` enum used by WhatsApp for AI bot messages.
- */
 export const ForwardOrigin = Object.freeze({
   BOT: 4,
 })
 
-/**
- * ButtonsMessage headerType enum. The legacy ButtonV2 fallback used 6
- * (LOCATION_THUMBNAIL) without documenting it — now explicit.
- */
 export const HeaderType = Object.freeze({
   EMPTY: 0,
   TEXT: 1,
   IMAGE: 3,
   VIDEO: 4,
   DOCUMENT: 5,
-  /** Pre-existing hack: location message with a JPEG thumbnail. */
   LOCATION_THUMBNAIL: 6,
 })
 
-/**
- * Native-flow biz/interactive node versions.
- */
 export const NativeFlow = Object.freeze({
-  /** Outer `<interactive v="1">` version. */
   OUTER_VERSION: '1',
-  /** Inner `<native_flow v="9">` version. */
   FLOW_VERSION: '9',
-  /** Default flow name when mixing button types. */
   FLOW_NAME_MIXED: 'mixed',
   TYPE: 'native_flow',
   BIZ_TAG: 'biz',
   INTERACTIVE_TAG: 'interactive',
 })
 
-/**
- * Hardcoded bot JID that WhatsApp expects inside `forwardedAiBotMessageInfo`.
- */
 export const BOT_JID = '0@bot'
 
-/**
- * Layout view-model kinds. Each becomes `GenAI{Kind}LayoutViewModel`.
- */
 export const LayoutKind = Object.freeze({
   SINGLE: 'Single',
   HSCROLL: 'HScroll',
   ACTION_ROW: 'ActionRow',
 })
 
-/**
- * Code-tokenizer highlight type numbers → string labels. Matches the
- * `TYPE_MAP` constant in the legacy AIRich.tokenizer.
- */
 export const HighlightType = Object.freeze({
   DEFAULT: 0,
   KEYWORD: 1,
@@ -97,7 +45,6 @@ export const HighlightType = Object.freeze({
   COMMENT: 5,
 })
 
-/** String labels corresponding to {@link HighlightType}. */
 export const HighlightLabel = Object.freeze({
   0: 'DEFAULT',
   1: 'KEYWORD',
@@ -107,34 +54,23 @@ export const HighlightLabel = Object.freeze({
   5: 'COMMENT',
 })
 
-/** `imagine_type` field on GenAIImaginePrimitive. */
 export const ImagineType = Object.freeze({
   IMAGE: 'IMAGE',
   ANIMATE: 'ANIMATE',
 })
 
-/** `source_type` field on GenAISearchResultPrimitive. */
 export const SourceType = Object.freeze({
   THIRD_PARTY: 'THIRD_PARTY',
 })
 
-/** `prompt_type` field on GenAIFollowUpSuggestionPillPrimitive. */
 export const PromptType = Object.freeze({
   SUGGESTED_PROMPT: 'SUGGESTED_PROMPT',
 })
 
-/** `sessionTransparencyType` field on botMetadata. */
 export const SessionTransparencyType = Object.freeze({
   DEFAULT: 1,
 })
 
-/**
- * All GenAI `__typename` strings. Single source of truth — typo-proof.
- *
- * NOTE: legacy code had `GenATableUXPrimitive` (missing the second 'I').
- * Verified against current WhatsApp Web wire format → the correct spelling
- * is `GenAITableUXPrimitive`. Lumina corrects this.
- */
 export const TYPENAME = Object.freeze({
   MARKDOWN_TEXT: 'GenAIMarkdownTextUXPrimitive',
   CODE: 'GenAICodeUXPrimitive',
@@ -147,12 +83,19 @@ export const TYPENAME = Object.freeze({
   METADATA_TEXT: 'GenAIMetadataTextPrimitive',
   FOLLOW_UP_PILL: 'GenAIFollowUpSuggestionPillPrimitive',
   UNIFIED_SECTION: 'GenAIUnifiedResponseSection',
-  /** Layout view-models are suffixed `GenAI{Kind}LayoutViewModel`. */
   layout(kind) {
     return `GenAI${kind}LayoutViewModel`
   },
 })
 
+export const SimpleButtonType = Object.freeze({
+  reply: 'quick_reply',
+  call: 'cta_call',
+  reminder: 'cta_reminder',
+  cancelReminder: 'cta_cancel_reminder',
+  address: 'address_message',
+})
+
 export default {
   MessageType,
   ForwardOrigin,
@@ -167,4 +110,5 @@ export default {
   PromptType,
   SessionTransparencyType,
   TYPENAME,
+  SimpleButtonType,
 }

package/src/proto/layouts.js

@@ -1,78 +1,17 @@
-/**
- * @file layouts.js
- * @module lumina/proto/layouts
- *
- * Layout view-model factories. Each layout wraps one or more UX primitives
- * inside `view_model`, with the proper `GenAI{Kind}LayoutViewModel` typename.
- *
- * Replaces the implicit `Array.isArray(data) ? 'primitives' : 'primitive'`
- * branching in the legacy `AIRich.newLayout` static method — explicit
- * single/hscroll/action-row variants instead.
- */
-
 import { LayoutKind, TYPENAME } from './enums.js'
 
-/**
- * Wrap a single primitive in a "Single" layout view-model.
- *
- * @param {object} primitive
- * @param {object} [extra]   Additional fields merged at top-level.
- * @returns {object}
- */
 export function singleLayout(primitive, extra = {}) {
-  return {
-    ...extra,
-    view_model: {
-      primitive,
-      __typename: TYPENAME.layout(LayoutKind.SINGLE),
-    },
-  }
+  return { ...extra, view_model: { primitive, __typename: TYPENAME.layout(LayoutKind.SINGLE) } }
 }
 
-/**
- * Wrap multiple primitives in an "HScroll" (horizontal scroll) layout.
- *
- * @param {object[]} primitives
- * @param {object} [extra]
- * @returns {object}
- */
 export function hscrollLayout(primitives, extra = {}) {
-  return {
-    ...extra,
-    view_model: {
-      primitives,
-      __typename: TYPENAME.layout(LayoutKind.HSCROLL),
-    },
-  }
+  return { ...extra, view_model: { primitives, __typename: TYPENAME.layout(LayoutKind.HSCROLL) } }
 }
 
-/**
- * Wrap multiple primitives in an "ActionRow" layout (used for follow-up
- * suggestion pills that should appear as a horizontal row of buttons).
- *
- * @param {object[]} primitives
- * @param {object} [extra]
- * @returns {object}
- */
 export function actionRowLayout(primitives, extra = {}) {
-  return {
-    ...extra,
-    view_model: {
-      primitives,
-      __typename: TYPENAME.layout(LayoutKind.ACTION_ROW),
-    },
-  }
+  return { ...extra, view_model: { primitives, __typename: TYPENAME.layout(LayoutKind.ACTION_ROW) } }
 }
 
-/**
- * Auto-pick helper. Picks `singleLayout` for a single primitive and
- * `hscrollLayout` for arrays — useful for API surfaces that accept both.
- *
- * @param {LayoutKind} kind    Forced kind; overrides auto-detection.
- * @param {object|object[]} data
- * @param {object} [extra]
- * @returns {object}
- */
 export function layoutFor(kind, data, extra = {}) {
   switch (kind) {
     case LayoutKind.SINGLE: