@heixui/dsh-session-suite 0.0.0-stage → 0.3.0

package/lib/factkeys.js

@@ -0,0 +1,212 @@
+/**
+ * Fact keys and supersession.
+ *
+ * Lexical similarity cannot see a value change: "拼团还没开" and "拼团开了" are
+ * two states of one fact that share almost no vocabulary, while "身高一米七"
+ * and "长胖到 55 公斤" share a lot but are two different facts. Keying each
+ * memory with `对象.方面` (for example `她.身高`) gives the engine something
+ * beyond the wording: entries that share a key describe the same slot, so the
+ * newest one wins and the older ones are marked superseded — kept in storage so
+ * the decision can be undone, but no longer recalled.
+ *
+ * This module is pure: no IO, no clock, no imports. The caller supplies the
+ * timestamps, and every function leaves its input untouched.
+ */
+
+/**
+ * Segments generic enough that a key built from them says nothing. A memory
+ * keyed `信息.内容` would collide with every other vague note, which is worse
+ * than no key at all, because the collision silently buries memories.
+ */
+export const CATCH_ALL_SEGMENTS = Object.freeze([
+  '信息',
+  '内容',
+  '事情',
+  '事项',
+  '记忆',
+  '其他',
+  '杂项',
+  'note',
+  'info',
+  'other',
+  'misc',
+  'general',
+])
+
+/** A catch-all key groups everything, so a key may have at most this many segments. */
+const MAX_SEGMENTS = 3
+
+/**
+ * Separator characters that all mean "segment boundary". Half-width `.` is the
+ * canonical form; the rest are the ones a model actually emits when asked for a
+ * dotted key in Chinese — the ideographic full stop and the middle dots.
+ */
+const SEPARATORS = /[.。·・/／．﹒]/g
+
+/** Every kind of whitespace, including the ideographic space. */
+const WHITESPACE = /\s+/g
+
+/** Only these shapes are parsed as a timestamp; anything else is "unknown". */
+const ISO_LIKE = /^\d{4}-\d{2}-\d{2}/
+
+/**
+ * Normalise a raw key to canonical form.
+ *
+ * Whitespace is dropped, separators are unified, empty segments collapse, ASCII
+ * is lowercased, and the result is trimmed of leading/trailing dots.
+ *
+ * @param {unknown} raw candidate key
+ * @returns {string | null} canonical key, or null when nothing usable remains
+ */
+export function normalizeFactKey(raw) {
+  if (typeof raw !== 'string') return null
+  // NFKC folds full-width ASCII (`ＡＢＣ`, `１`, `．`) onto its half-width form,
+  // which is what makes `她．身高` and `她.身高` the same key.
+  const folded = raw.normalize('NFKC')
+  const segments = folded
+    .replace(SEPARATORS, '.')
+    .replace(WHITESPACE, '')
+    .split('.')
+    .map(segment => segment.replace(/[A-Z]/g, ch => ch.toLowerCase()))
+    .filter(segment => segment.length > 0)
+  if (segments.length === 0) return null
+  return segments.join('.')
+}
+
+/**
+ * Is this key too broad to group memories safely?
+ *
+ * A key is catch-all when it has no usable segment (null, empty, punctuation
+ * only), a single segment, more than three segments, or any segment drawn from
+ * {@link CATCH_ALL_SEGMENTS}. The raw value is accepted as well as a canonical
+ * one, so callers cannot forget to normalise first.
+ *
+ * @param {unknown} key key to judge
+ * @returns {boolean} true when the key must not be used for supersession
+ */
+export function isCatchAllKey(key) {
+  const canonical = normalizeFactKey(key)
+  if (!canonical) return true
+  const segments = canonical.split('.')
+  if (segments.length < 2 || segments.length > MAX_SEGMENTS) return true
+  return segments.some(segment => CATCH_ALL_SEGMENTS.includes(segment))
+}
+
+/**
+ * Read an entry's timestamp as a comparable number.
+ *
+ * @param {unknown} value `createdAt` in any accepted shape
+ * @returns {number | null} epoch milliseconds, or null when it cannot be judged
+ */
+function comparableTime(value) {
+  if (typeof value === 'number') return Number.isFinite(value) ? value : null
+  if (value instanceof Date) {
+    const time = value.getTime()
+    return Number.isFinite(time) ? time : null
+  }
+  if (typeof value === 'string' && ISO_LIKE.test(value)) {
+    const time = Date.parse(value)
+    return Number.isFinite(time) ? time : null
+  }
+  return null
+}
+
+/**
+ * Work out which entries a fact key retires.
+ *
+ * Rules:
+ * - Entries are grouped by canonical key. Entries without a key, with an
+ *   unparsable key, or with a catch-all key never participate.
+ * - Within a group the greatest `createdAt` survives; every entry strictly
+ *   older than it is superseded.
+ * - **Exact timestamp ties supersede nothing.** When two entries claim the same
+ *   slot at the same instant there is no basis for ordering them, and guessing
+ *   would permanently bury a real memory, so both stay live.
+ * - Entries whose timestamp cannot be read are likewise kept.
+ *
+ * Grouping by canonical key also means `她.身高` and `她。身高` compete, and the
+ * result does not depend on input order (only `byId` uses the first tied winner
+ * when several entries share the greatest timestamp).
+ *
+ * @param {Array<{id?: string, factKey?: unknown, createdAt?: unknown}>} entries memories
+ * @returns {{superseded: Array<{id: unknown, byId: unknown, factKey: string}>, kept: unknown[]}}
+ */
+export function converge(entries) {
+  const list = Array.isArray(entries) ? entries : []
+  /** @type {Map<string, number[]>} */
+  const groups = new Map()
+
+  for (let index = 0; index < list.length; index += 1) {
+    const entry = list[index]
+    if (!entry || typeof entry !== 'object') continue
+    const key = normalizeFactKey(entry.factKey)
+    if (!key || isCatchAllKey(key)) continue
+    const bucket = groups.get(key)
+    if (bucket) bucket.push(index)
+    else groups.set(key, [index])
+  }
+
+  const superseded = []
+  const retired = new Set()
+  const times = list.map(entry => (entry && typeof entry === 'object' ? comparableTime(entry.createdAt) : null))
+
+  for (const [key, indexes] of groups) {
+    if (indexes.length < 2) continue
+    const timed = indexes.filter(index => times[index] !== null)
+    if (timed.length === 0) continue
+    let newest = timed[0]
+    for (const index of timed) {
+      // Strict `>` keeps the first entry of an exact tie as `byId`; the tie
+      // itself supersedes nothing, which is enforced by the strict `<` below.
+      if (times[index] > times[newest]) newest = index
+    }
+    for (const index of timed) {
+      if (times[index] < times[newest]) {
+        retired.add(index)
+        superseded.push({ id: list[index].id, byId: list[newest].id, factKey: key })
+      }
+    }
+  }
+
+  const kept = []
+  for (let index = 0; index < list.length; index += 1) {
+    if (!retired.has(index)) kept.push(list[index]?.id)
+  }
+  return { superseded, kept }
+}
+
+/**
+ * Annotate a copy of the entry list with the supersession verdict.
+ *
+ * Superseded entries gain `supersededBy` (the surviving id) and `supersededAt`
+ * (the surviving entry's `createdAt`, so the stamp is deterministic); every
+ * other field and every other entry is copied through unchanged. The input
+ * objects are never written to — callers can undo a supersession by dropping
+ * those two fields again.
+ *
+ * @param {Array<object>} entries memories
+ * @param {{now?: number}} [options] override the recorded `supersededAt`
+ * @returns {Array<object>} new array, same length and order as the input
+ */
+export function applySupersession(entries, options = {}) {
+  const list = Array.isArray(entries) ? entries : []
+  const { superseded } = converge(list)
+  const override = options && typeof options === 'object' ? comparableTime(options.now) : null
+
+  const byId = new Map()
+  const entryById = new Map()
+  for (const entry of list) {
+    if (entry && typeof entry === 'object') entryById.set(entry.id, entry)
+  }
+  for (const item of superseded) {
+    if (!byId.has(item.id)) byId.set(item.id, item.byId)
+  }
+
+  return list.map(entry => {
+    if (!entry || typeof entry !== 'object') return entry
+    if (!byId.has(entry.id)) return { ...entry }
+    const survivor = entryById.get(byId.get(entry.id))
+    const at = override ?? comparableTime(survivor?.createdAt)
+    return { ...entry, supersededBy: byId.get(entry.id), supersededAt: at }
+  })
+}

package/lib/markdown.js

@@ -0,0 +1,252 @@
+/**
+ * A small Markdown subset parser shared by the HTML and image exports.
+ *
+ * The export pipeline must not depend on a markup library (a Host plugin cannot
+ * import extra packages), and both renderers need the *same* structure: headings,
+ * paragraphs, lists, quotes, fenced code, and inline emphasis. So the Host parses
+ * once into blocks with inline runs, the HTML renderer emits markup, and the
+ * browser draws the very same runs on a canvas.
+ *
+ * Supported: `#`–`######`, paragraphs, `-`/`*`/`+` and `1.` lists (indent = nesting),
+ * `>` quotes, ``` fenced code, `---` rules, `**bold**`, `*italic*`, `` `code` ``,
+ * `[text](url)`. Anything else stays literal text, which is the right failure mode
+ * for a transcript.
+ */
+
+/**
+ * Split one line of inline Markdown into styled runs.
+ *
+ * @param {string} text inline source
+ * @returns {{ text: string, bold?: true, italic?: true, code?: true, href?: string }[]} runs
+ */
+export function inlineRuns(text) {
+  const source = String(text ?? '')
+  const pattern = /(\*\*[^*]+\*\*|__[^_]+__|`[^`]+`|\*[^*\n]+\*|_[^_\n]+_|\[[^\]]+\]\([^)\s]+\))/g
+  const runs = []
+  let last = 0
+  for (const match of source.matchAll(pattern)) {
+    if (match.index > last) runs.push({ text: source.slice(last, match.index) })
+    const token = match[0]
+    if (token.startsWith('**') || token.startsWith('__')) runs.push({ text: token.slice(2, -2), bold: true })
+    else if (token.startsWith('`')) runs.push({ text: token.slice(1, -1), code: true })
+    else if (token.startsWith('[')) {
+      const link = /^\[([^\]]+)\]\(([^)\s]+)\)$/.exec(token)
+      if (link) runs.push({ text: link[1], href: link[2] })
+      else runs.push({ text: token })
+    } else runs.push({ text: token.slice(1, -1), italic: true })
+    last = match.index + token.length
+  }
+  if (last < source.length) runs.push({ text: source.slice(last) })
+  return runs.length > 0 ? runs : [{ text: '' }]
+}
+
+/**
+ * Parse a Markdown document into blocks.
+ *
+ * @param {string} source markdown
+ * @returns {any[]} blocks
+ */
+export function parseMarkdown(source) {
+  const lines = String(source ?? '').replace(/\r\n?/g, '\n').split('\n')
+  const blocks = []
+  let paragraph = []
+  let index = 0
+
+  const flush = () => {
+    if (paragraph.length === 0) return
+    blocks.push({ type: 'paragraph', runs: inlineRuns(paragraph.join('\n').trim()) })
+    paragraph = []
+  }
+
+  while (index < lines.length) {
+    const line = lines[index]
+
+    if (/^\s*```/.test(line)) {
+      flush()
+      const lang = line.trim().slice(3).trim()
+      const body = []
+      index += 1
+      while (index < lines.length && !/^\s*```/.test(lines[index])) {
+        body.push(lines[index])
+        index += 1
+      }
+      index += 1
+      blocks.push({ type: 'code', lang, text: body.join('\n') })
+      continue
+    }
+
+    if (/^\s*$/.test(line)) {
+      flush()
+      index += 1
+      continue
+    }
+
+    const heading = /^(#{1,6})\s+(.*)$/.exec(line)
+    if (heading) {
+      flush()
+      blocks.push({ type: 'heading', level: heading[1].length, runs: inlineRuns(heading[2].trim()) })
+      index += 1
+      continue
+    }
+
+    if (/^\s*(?:-{3,}|\*{3,}|_{3,})\s*$/.test(line)) {
+      flush()
+      blocks.push({ type: 'hr' })
+      index += 1
+      continue
+    }
+
+    // Pipe table: a header row immediately followed by a separator row.
+    const separator = /^\s*\|?[\s:|-]*-[\s:|-]*\|[\s:|-]*$/
+    if (/^\s*\|.*\|\s*$/.test(line) && index + 1 < lines.length && separator.test(lines[index + 1]) && lines[index + 1].includes('-')) {
+      flush()
+      const cells = row => row.trim().replace(/^\|/, '').replace(/\|$/, '').split('|').map(cell => cell.trim())
+      const headers = cells(line).map(cell => inlineRuns(cell))
+      index += 2
+      const rows = []
+      while (index < lines.length && /^\s*\|.*\|\s*$/.test(lines[index])) {
+        rows.push(cells(lines[index]).map(cell => inlineRuns(cell)))
+        index += 1
+      }
+      blocks.push({ type: 'table', headers, rows })
+      continue
+    }
+
+    if (/^\s*>/.test(line)) {
+      flush()
+      const quote = []
+      while (index < lines.length && /^\s*>/.test(lines[index])) {
+        quote.push(lines[index].replace(/^\s*>\s?/, ''))
+        index += 1
+      }
+      blocks.push({ type: 'quote', lines: quote.map(entry => inlineRuns(entry.trim())).filter(runs => runs.some(run => run.text.trim())) })
+      continue
+    }
+
+    const bullet = /^(\s*)([-*+])\s+(.*)$/.exec(line)
+    const ordered = /^(\s*)(\d+)[.)]\s+(.*)$/.exec(line)
+    if (bullet || ordered) {
+      flush()
+      const isOrdered = Boolean(ordered)
+      const items = []
+      while (index < lines.length) {
+        const nextBullet = /^(\s*)([-*+])\s+(.*)$/.exec(lines[index])
+        const nextOrdered = /^(\s*)(\d+)[.)]\s+(.*)$/.exec(lines[index])
+        const match = isOrdered ? nextOrdered : nextBullet
+        if (match) {
+          items.push({ indent: Math.floor(match[1].replace(/\t/g, '  ').length / 2), runs: inlineRuns(match[3].trim()) })
+          index += 1
+          continue
+        }
+        if (items.length > 0 && /^\s{2,}\S/.test(lines[index])) {
+          const continuation = lines[index].trim()
+          const lastItem = items[items.length - 1]
+          lastItem.runs = inlineRuns(`${runsToText(lastItem.runs)} ${continuation}`)
+          index += 1
+          continue
+        }
+        break
+      }
+      blocks.push({ type: 'list', ordered: isOrdered, start: isOrdered ? Number(ordered[2]) : 1, items })
+      continue
+    }
+
+    paragraph.push(line)
+    index += 1
+  }
+
+  flush()
+  return blocks
+}
+
+/** @param {readonly any[]} runs runs @returns {string} plain text */
+export function runsToText(runs) {
+  return (runs ?? []).map(run => run.text ?? '').join('')
+}
+
+/** @param {string} value raw @returns {string} HTML-safe */
+export function escapeHtml(value) {
+  return String(value ?? '').replace(/[&<>"']/g, char => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[char])
+}
+
+/**
+ * @param {readonly any[]} runs runs
+ * @returns {string} inline HTML
+ */
+export function runsToHtml(runs) {
+  return (runs ?? [])
+    .map(run => {
+      let html = escapeHtml(run.text ?? '')
+      if (run.code) html = `<code>${html}</code>`
+      if (run.bold) html = `<strong>${html}</strong>`
+      if (run.italic) html = `<em>${html}</em>`
+      if (run.href) html = `<a href="${escapeHtml(run.href)}" rel="noreferrer noopener" target="_blank">${html}</a>`
+      return html
+    })
+    .join('')
+}
+
+/**
+ * @param {readonly any[]} blocks parsed blocks
+ * @returns {string} block HTML
+ */
+export function blocksToHtml(blocks) {
+  const out = []
+  for (const block of blocks ?? []) {
+    if (block.type === 'heading') {
+      const level = Math.min(6, Math.max(1, block.level ?? 2) + 1)
+      out.push(`<h${level}>${runsToHtml(block.runs)}</h${level}>`)
+    } else if (block.type === 'paragraph') {
+      out.push(`<p>${runsToHtml(block.runs).replace(/\n/g, '<br>')}</p>`)
+    } else if (block.type === 'list') {
+      const tag = block.ordered ? 'ol' : 'ul'
+      const startAttr = block.ordered && block.start !== 1 ? ` start="${block.start}"` : ''
+      const items = block.items
+        .map(item => {
+          const depth = Math.min(3, item.indent ?? 0)
+          return `<li class="depth-${depth}">${runsToHtml(item.runs)}</li>`
+        })
+        .join('')
+      out.push(`<${tag}${startAttr}>${items}</${tag}>`)
+    } else if (block.type === 'quote') {
+      out.push(`<blockquote>${(block.lines ?? []).map(runs => `<p>${runsToHtml(runs)}</p>`).join('')}</blockquote>`)
+    } else if (block.type === 'table') {
+      const head = (block.headers ?? []).map(runs => `<th>${runsToHtml(runs)}</th>`).join('')
+      const body = (block.rows ?? [])
+        .map(row => `<tr>${row.map(runs => `<td>${runsToHtml(runs)}</td>`).join('')}</tr>`)
+        .join('')
+      out.push(`<div class="table-wrap"><table><thead><tr>${head}</tr></thead><tbody>${body}</tbody></table></div>`)
+    } else if (block.type === 'code') {
+      out.push(`<pre><code>${escapeHtml(block.text)}</code></pre>`)
+    } else if (block.type === 'hr') {
+      out.push('<hr>')
+    }
+  }
+  return out.join('\n')
+}
+
+/**
+ * Plain one-line preview of a Markdown string, for menu and picker rows.
+ *
+ * @param {string} text markdown
+ * @param {number} [limit] character budget
+ * @returns {string} preview
+ */
+export function previewText(text, limit = 120) {
+  const plain = String(text ?? '')
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/!\[[^\]]*\]\([^)]*\)/g, ' ')
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+    // attachment placeholders are honest in an export but useless in a menu row.
+    // The counted form ("［3 张图片］") must go first: the generic rule below
+    // would otherwise eat only the trailing "图片］" and leave "［3 张".
+    .replace(/［\s*\d+\s*张(?:图片|文件)\s*］/g, ' ')
+    .replace(/［文件：[^］]*］/g, ' ')
+    .replace(/\[image: [^\]]*\]/g, ' ')
+    .replace(/［?(?:图片|image|file)[^］\]]*］?/g, ' ')
+    .replace(/^\s{0,3}#{1,6}\s+/gm, '')
+    .replace(/[*_`>]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+  return plain.length > limit ? `${plain.slice(0, limit)}…` : plain
+}