@aihu-plugin/kindly-note

Aihu — agentic discovery and interaction, for human purpose.

Runtime syntax highlighting + markdown rendering for aihu — / custom elements + signal-aware highlight()/renderMarkdown() helpers, powered by published @kindly-note/* packages with lazy loading.

Held-private workspace package. Not yet published to npm.

Status: Held private — not yet published to npm. See v1.1 roadmap for ratification gating (e.g. RFC #56 live-binding for @aihu/plugin enforcement).

Runtime syntax highlighting and markdown rendering for aihu, powered by the published @kindly-note/* packages. Ships two custom elements and two signal-aware helpers, all rendered in the browser, at runtime, with lazy-loaded peers:

• Highlighting — <aihu-code> + highlight() render scoped-span HTML, with per-language tokenizers fetched on demand (~1.5 kB gz each).
• Markdown rendering — <aihu-markdown> + renderMarkdown() render CommonMark to safe semantic HTML via @kindly-note/render-markdown (raw HTML escaped, javascript:/unsafe data: URLs neutralised, on* handlers never emitted — safe for innerHTML).

Peer dependencies

The kindly-note engine + emitter + lazy loader are peer dependencies for the highlighting half:

bun add @kindly-note/core @kindly-note/emitters-html @kindly-note/loader-dynamic-import

For the markdown half, add the one-call renderer (it pulls in @kindly-note/emitters-markdown + @kindly-note/lang-markdown transitively):

bun add @kindly-note/render-markdown

Language tokenizers are fetched on demand via dynamic import(). Install the ones you intend to use so the resolver can find them:

bun add @kindly-note/lang-typescript @kindly-note/lang-json @kindly-note/lang-markdown

Pair with a theme for the kn-* classes:

import '@kindly-note/themes-default/dark.css'

Usage

<aihu-code> element

import { defineCodeElement } from '@aihu-plugin/kindly-note'
defineCodeElement() // registers <aihu-code> (idempotent, SSR-safe)

<aihu-code lang="typescript">const x: number = 1</aihu-code>

Signal-driven (re-highlights automatically when the signal changes):

import { signal } from '@aihu/signals'
const [code, setCode] = signal('const a = 1')

const el = document.createElement('aihu-code')
el.language = 'typescript' // JS property is `language` (native `lang` is reserved)
el.code = code // pass the signal reader → element subscribes
document.body.append(el)

setCode('let b = 2') // <aihu-code> re-highlights

highlight() helper

import { highlight } from '@aihu-plugin/kindly-note'

const { html, language, fallback } = await highlight('{"a": 1}', 'json')
// html === '<span class="kn-punctuation">{</span>…'

highlight() never throws: an unknown language returns the HTML-escaped source with fallback: true.

<aihu-markdown> element

import { defineMarkdownElement } from '@aihu-plugin/kindly-note'
defineMarkdownElement() // registers <aihu-markdown> (idempotent, SSR-safe)

<aihu-markdown># Hello

**bold** and a [link](https://example.com).</aihu-markdown>

Rendered markup lands in an open shadow root. Signal-driven (re-renders automatically when the signal changes):

import { signal } from '@aihu/signals'
const [md, setMd] = signal('# First')

const el = document.createElement('aihu-markdown')
el.source = md // pass the signal reader → element subscribes (alias: `el.markdown`)
document.body.append(el)

setMd('## Second') // <aihu-markdown> re-renders

renderMarkdown() helper

import { renderMarkdown } from '@aihu-plugin/kindly-note'

const html = await renderMarkdown('# Hi\n\n**bold**')
// html === '<h1>Hi</h1>\n<p><strong>bold</strong></p>' — safe for innerHTML

Security-first by default: raw HTML is escaped and dangerous URL schemes are neutralised. Highlight code fences by passing language packs:

import json from '@kindly-note/lang-json'
const html = await renderMarkdown('```json\n{"a": 1}\n```', { languages: [json] })

GFM (tables / task-lists / strikethrough / autolinks) is intentionally not supported — that lives in @kindly-note/lang-markdown-gfm.

Plugin registration

// aihu.config.ts
import { kindlyNote } from '@aihu-plugin/kindly-note'
import { defineAihuConfig } from '@aihu/server'

export default defineAihuConfig({ plugins: [kindlyNote()] })

Scope

This package ships both halves: syntax highlighting (<aihu-code> / highlight()) and markdown rendering (<aihu-markdown> / renderMarkdown), the latter via the published @kindly-note/render-markdown. CommonMark only — GFM (tables / task-lists / strikethrough / autolinks) is out of scope and lives in @kindly-note/lang-markdown-gfm.

Install

npm install @aihu-plugin/kindly-note
# or
bun add @aihu-plugin/kindly-note

Auto-generated against @aihu-plugin/[email protected].

Package facts

| | | |---|---| | Version | 0.2.1 | | Tier | E — Held private (unmapped tier) | | Published files | 3 entries | | License | MIT |

Auto-generated against @aihu-plugin/[email protected].

Exports

| Subpath | ESM | CJS | |---|---|---| | . | ./dist/index.js | — |

Auto-generated against @aihu-plugin/[email protected].

Dependencies

Dependencies:

• @aihu/signals — workspace:*

Peer dependencies:

• @kindly-note/core — ^0.2.0
• @kindly-note/emitters-html — ^0.1.0
• @kindly-note/loader-dynamic-import — ^0.1.0
• @kindly-note/render-markdown — ^0.1.0

Auto-generated against @aihu-plugin/[email protected].

See also

• Aihu framework root
• v1.1 roadmap

Auto-generated against @aihu-plugin/[email protected].

License

MIT — see LICENSE.

Auto-generated against @aihu-plugin/[email protected].