@jackens/nnn 2026.9.9 → 2026.9.29

package/README.md

@@ -0,0 +1,1229 @@
+# nnn
+
+A collection of Jackens’ JavaScript helper utilities (version: `2026.9.29`).
+
+## Installation
+
+```sh
+bun i @jackens/nnn
+```
+
+or
+
+```sh
+npm i @jackens/nnn
+```
+
+## Usage
+
+```js
+import {
+  CNode,
+  HArgs,
+  HArgs1,
+  LexerSpec,
+  LexerSpecOptions,
+  c,
+  createLexer,
+  h,
+  monokai,
+  nanolightTs,
+  rwd,
+  s,
+  svgUse,
+} from '@jackens/nnn' // or './node_modules/@jackens/nnn/nnn.js'
+```
+
+## Exports
+
+- [`CNode`](#CNode):
+  Represents a CSS rule node for the [`c`](#c) helper. Keys are CSS properties or nested selectors.
+- [`HArgs`](#HArgs):
+  Tuple argument type for the [`h`](#h) and [`s`](#s) helpers.
+- [`HArgs1`](#HArgs1):
+  Single argument type for the [`h`](#h) and [`s`](#s) helpers.
+- [`LexerSpec`](#LexerSpec):
+  A [`createLexer`](#createLexer) spec: a `[metadata, pattern, options?]` tuple.
+- [`LexerSpecOptions`](#LexerSpecOptions):
+  Options of a [`createLexer`](#createLexer) spec controlling the lexer state stack.
+- [`c`](#c):
+  A minimal CSS-in-JS helper that converts a JavaScript object hierarchy into a CSS string.
+- [`createLexer`](#createLexer):
+  A helper for building simple stateful lexers (see also [`nanolightTs`](#nanolightTs)).
+- [`h`](#h):
+  A lightweight _HyperScript_-style helper for creating and modifying `HTMLElement`s (see also [`s`](#s)).
+- [`monokai`](#monokai):
+  A Monokai-inspired color scheme for use with the [`c`](#c) helper and [`nanolightTs`](#nanolightTs) lexer.
+- [`nanolightTs`](#nanolightTs):
+  A TypeScript/JavaScript syntax highlighting lexer built using [`createLexer`](#createLexer).
+- [`rwd`](#rwd):
+  A responsive web design helper that generates CSS rules for a grid-like layout of floating elements.
+- [`s`](#s):
+  A lightweight _HyperScript_-style helper for creating and modifying `SVGElement`s (see also [`h`](#h)).
+- [`svgUse`](#svgUse):
+  Shorthand for creating an `<svg>` element with a `<use>` child referencing a symbol (e.g. an icon) by ID.
+
+### CNode
+
+```ts
+type CNode = {
+  [attributeOrSelector: string]: string | number | CNode | undefined
+}
+```
+
+Represents a CSS rule node for the [`c`](#c) helper. Keys are CSS properties or nested selectors.
+
+### HArgs
+
+```ts
+type HArgs = [string | Node, ...HArgs1[]]
+```
+
+Tuple argument type for the [`h`](#h) and [`s`](#s) helpers.
+
+### HArgs1
+
+```ts
+type HArgs1 = Record<PropertyKey, unknown> | null | undefined | Node | string | number | HArgs
+```
+
+Single argument type for the [`h`](#h) and [`s`](#s) helpers.
+
+### LexerSpec
+
+```ts
+type LexerSpec<M> = [metadata: M, pattern: string | RegExp, options?: LexerSpecOptions]
+```
+
+A [`createLexer`](#createLexer) spec: a `[metadata, pattern, options?]` tuple.
+
+### LexerSpecOptions
+
+```ts
+type LexerSpecOptions = {
+  in?: string | string[]
+  pop?: boolean
+  push?: string
+}
+```
+
+Options of a [`createLexer`](#createLexer) spec controlling the lexer state stack.
+
+#### in
+
+State(s) in which the spec is active (default: `'root'`).
+
+#### pop
+
+Whether to pop the current state off the stack after a match (the `'root'` state at the bottom is never popped).
+
+#### push
+
+State to push onto the stack after a match (applied after `pop`).
+
+### c
+
+```ts
+const c: (node: CNode, splitter?: string) => string
+```
+
+A minimal CSS-in-JS helper that converts a JavaScript object hierarchy into a CSS string.
+
+#### node
+
+An object describing CSS rules.
+Keys are selectors or at-rules; values are either CSS property values or nested rule objects.
+Nested selectors are appended to the parent selector as is (e.g. `'.c'` inside `a` → `a.c`), so a leading space is needed for a descendant combinator (e.g. `' .c'` → `a .c`).
+A selector key may contain comma-separated alternatives (e.g. `'.b,.c'`); when nested, each alternative is combined with each parent alternative (cartesian product), producing a comma-joined selector list (e.g. `'a.b,a.c'`).
+Top-level at-rules (e.g. `'@media …'`) wrap their nested rules; inside a top-level `:root` rule nested keys are concatenated into property names (e.g. `{ ':root': { '--': { bg: 'red' } } }` → `:root{--bg:red}`).
+`null`/`undefined` values are skipped.
+
+#### splitter
+
+A delimiter used to create unique keys (default: `'$$'`).
+The substring from `splitter` to the end of a key is ignored (e.g. `src$$1` → `src`).
+
+#### Returns
+
+A CSS string representing the compiled rules.
+
+#### Usage Examples
+
+```ts
+const actual = c({
+  a: {
+    color: 'red',
+    margin: 1,
+    '.c': { margin: 2, padding: 2 },
+    padding: 1,
+  },
+})
+
+const expected = `
+  a{
+    color:red;
+    margin:1
+  }
+  a.c{
+    margin:2;
+    padding:2
+  }
+  a{
+    padding:1
+  }
+`.replace(/\n\s*/g, '')
+
+expect(actual).toBe(expected)
+```
+
+```ts
+const actual = c({
+  a: {
+    '.b': {
+      color: 'red',
+      margin: 1,
+      '.c': { margin: 2, padding: 2 },
+      padding: 1,
+    },
+  },
+})
+
+const expected = `
+  a.b{
+    color:red;
+    margin:1
+  }
+  a.b.c{
+    margin:2;
+    padding:2
+  }
+  a.b{
+    padding:1
+  }
+`.replace(/\n\s*/g, '')
+
+expect(actual).toBe(expected)
+```
+
+```ts
+const actual = c({
+  '@font-face$$1': {
+    'font-family': 'Jackens',
+    src$$1: 'url(otf/jackens.otf)',
+    src$$2: "url(otf/jackens.otf) format('opentype')," + "url(svg/jackens.svg) format('svg')",
+    'font-weight': 'normal',
+    'font-style': 'normal',
+  },
+  '@font-face$$2': {
+    'font-family': 'C64',
+    src: 'url(fonts/C64_Pro_Mono-STYLE.woff)',
+  },
+  '@keyframes spin': {
+    '0%': { transform: 'rotate(0deg)' },
+    '100%': { transform: 'rotate(360deg)' },
+  },
+  div: {
+    border: 'solid red 1px',
+    '.c1': { 'background-color': '#000' },
+    ' .c1': { 'background-color': 'black' },
+    '.c2': { 'background-color': 'rgb(0,0,0)' },
+  },
+  '@media(min-width:200px)': {
+    div: { margin: 0, padding: 0 },
+    span: { color: '#000' },
+  },
+})
+
+const expected = `
+  @font-face{
+    font-family:Jackens;
+    src:url(otf/jackens.otf);
+    src:url(otf/jackens.otf) format('opentype'),url(svg/jackens.svg) format('svg');
+    font-weight:normal;
+    font-style:normal
+  }
+  @font-face{
+    font-family:C64;
+    src:url(fonts/C64_Pro_Mono-STYLE.woff)
+  }
+  @keyframes spin{
+    0%{
+      transform:rotate(0deg)
+    }
+    100%{
+      transform:rotate(360deg)
+    }
+  }
+  div{
+    border:solid red 1px
+  }
+  div.c1{
+    background-color:#000
+  }
+  div .c1{
+    background-color:black
+  }
+  div.c2{
+    background-color:rgb(0,0,0)
+  }
+  @media(min-width:200px){
+    div{
+      margin:0;
+      padding:0
+    }
+    span{
+      color:#000
+    }
+  }
+`.replace(/\n\s*/g, '')
+
+expect(actual).toBe(expected)
+```
+
+```ts
+const actual = c({
+  a: {
+    '.b,.c': {
+      margin: 1,
+      '.d': {
+        margin: 2,
+      },
+    },
+  },
+})
+
+const expected = `
+  a.b,a.c{
+    margin:1
+  }
+  a.b.d,a.c.d{
+    margin:2
+  }
+`.replace(/\n\s*/g, '')
+
+expect(actual).toBe(expected)
+```
+
+```ts
+const actual = c({
+  '.b,.c': {
+    margin: 1,
+    '.d': {
+      margin: 2,
+    },
+  },
+})
+
+const expected = `
+  .b,.c{
+    margin:1
+  }
+  .b.d,.c.d{
+    margin:2
+  }
+`.replace(/\n\s*/g, '')
+
+expect(actual).toBe(expected)
+```
+
+```ts
+const actual = c({
+  '.a,.b': {
+    margin: 1,
+    '.c,.d': {
+      margin: 2,
+    },
+  },
+})
+
+const expected = `
+  .a,.b{
+    margin:1
+  }
+  .a.c,.a.d,.b.c,.b.d{
+    margin:2
+  }
+`.replace(/\n\s*/g, '')
+
+expect(actual).toBe(expected)
+```
+
+```ts
+const actual = c({
+  ':root$$monokai': {
+    '--': {
+      bg: '#faf4f2',
+      fg: '#29242a',
+      comment: '#918c8e',
+      identifier: {
+        1: '#7058be',
+        2: '#269d69',
+        3: '#1c8ca8',
+        4: '#29242a',
+      },
+      keyword: {
+        1: '#e14775',
+        2: '#7058be',
+        3: '#1c8ca8',
+      },
+      number: '#7058be',
+      operator: '#e14775',
+      punctuation: '#918c8e',
+      string: '#cc7a0a',
+    },
+  },
+  '@media only screen and (prefers-color-scheme: dark)$$monokai': {
+    ':root': {
+      '--': {
+        bg: '#2d2a2e',
+        fg: '#fcfcfa',
+        comment: '#727072',
+        identifier: {
+          1: '#ae81ff',
+          2: '#a9dc76',
+          3: '#66d9ef',
+          4: '#fcfcfa',
+        },
+        keyword: {
+          1: '#ff6188',
+          2: '#ae81ff',
+          3: '#66d9ef',
+        },
+        number: '#ae81ff',
+        operator: '#ff6188',
+        punctuation: '#727072',
+        string: '#ffd866',
+      },
+    },
+  },
+})
+
+const expected = `
+  :root{
+    --bg:#faf4f2;
+    --fg:#29242a;
+    --comment:#918c8e;
+    --identifier1:#7058be;
+    --identifier2:#269d69;
+    --identifier3:#1c8ca8;
+    --identifier4:#29242a;
+    --keyword1:#e14775;
+    --keyword2:#7058be;
+    --keyword3:#1c8ca8;
+    --number:#7058be;
+    --operator:#e14775;
+    --punctuation:#918c8e;
+    --string:#cc7a0a
+  }
+  @media only screen and (prefers-color-scheme: dark){
+    :root{
+      --bg:#2d2a2e;
+      --fg:#fcfcfa;
+      --comment:#727072;
+      --identifier1:#ae81ff;
+      --identifier2:#a9dc76;
+      --identifier3:#66d9ef;
+      --identifier4:#fcfcfa;
+      --keyword1:#ff6188;
+      --keyword2:#ae81ff;
+      --keyword3:#66d9ef;
+      --number:#ae81ff;
+      --operator:#ff6188;
+      --punctuation:#727072;
+      --string:#ffd866
+    }
+  }
+`.replace(/\n\s*/g, '')
+
+expect(actual).toBe(expected)
+```
+
+### createLexer
+
+```ts
+const createLexer: <M, T>(
+  decorator: (chunk: string, metadata?: M) => T,
+  ...specs: LexerSpec<M>[]
+) => (code: string) => T[]
+```
+
+A helper for building simple stateful lexers (see also [`nanolightTs`](#nanolightTs)).
+
+#### Remarks
+
+1. Matches starting at an earlier position take precedence.
+2. Among matches at the same position, the longer one wins.
+3. Among matches of the same position and length, the one defined earlier wins.
+4. Only specs active in the current state (the top of the state stack, initially `'root'`) are considered.
+5. Patterns are matched against the whole input, so `^`, `$`, `\b` and lookbehinds see the text around the current position; a sticky (`y`) `RegExp` matches only at the current position.
+6. Empty matches are ignored.
+
+#### decorator
+
+A function that wraps each chunk of the input.
+It receives the matched text (`chunk`) and the `metadata` of the spec whose pattern produced the match.
+For unmatched text between matches, `metadata` is `undefined`.
+
+#### specs
+
+An array of tuples `[metadata, pattern, options?]` where:
+
+- `metadata`: arbitrary data (e.g., a CSS class name) passed to `decorator` when the pattern matches.
+- `pattern`: a `string` (matched literally) or `RegExp` to match against the input.
+- `options`: optional [`LexerSpecOptions`](#LexerSpecOptions) (states in which the spec is active and state transitions).
+
+#### Returns
+
+A lexer function that accepts an input string and returns an array of decorated chunks covering the whole input (in order).
+
+#### Usage Examples
+
+```ts
+const lexer = createLexer(
+  (chunk, metadata) => ({ chunk, metadata }),
+  ['keyword', /\b(if|else|for)\b/],
+  ['string', /"[^"]*"/]
+)
+
+const result = lexer('if "hello" else "world"')
+
+expect(result).toEqual([
+  { chunk: 'if', metadata: 'keyword' },
+  { chunk: ' ', metadata: undefined },
+  { chunk: '"hello"', metadata: 'string' },
+  { chunk: ' ', metadata: undefined },
+  { chunk: 'else', metadata: 'keyword' },
+  { chunk: ' ', metadata: undefined },
+  { chunk: '"world"', metadata: 'string' },
+])
+```
+
+```ts
+const lexer = createLexer((chunk, metadata) => `${metadata}:${chunk}`, ['tag', 'BEGIN'], ['end', 'END'])
+
+const result = lexer('aBEGINbENDc')
+
+expect(result).toEqual(['undefined:a', 'tag:BEGIN', 'undefined:b', 'end:END', 'undefined:c'])
+```
+
+```ts
+const lexer = createLexer(chunk => chunk, ['test', /test/])
+
+const result = lexer('')
+
+expect(result).toEqual([])
+```
+
+```ts
+const lexer = createLexer((chunk, metadata) => ({ chunk, metadata }), ['start', /^test/])
+
+const result = lexer('test here')
+
+expect(result).toEqual([
+  { chunk: 'test', metadata: 'start' },
+  { chunk: ' here', metadata: undefined },
+])
+```
+
+```ts
+const lexer = createLexer((chunk, metadata) => metadata, ['later', /x/], ['earlier', /y/])
+
+const result = lexer('yx')
+
+expect(result).toEqual(['earlier', 'later'])
+```
+
+```ts
+const lexer = createLexer(chunk => chunk, ['short', 'a'], ['long', 'abc'])
+
+const result = lexer('abc')
+
+expect(result).toEqual(['abc'])
+```
+
+```ts
+const lexer = createLexer(chunk => chunk, ['empty', ''], ['word', /\w+/])
+
+const result = lexer('hello')
+
+expect(result).toEqual(['hello'])
+```
+
+```ts
+const lexer = createLexer(chunk => chunk, ['test', /xyz/])
+
+const result = lexer('abc')
+
+expect(result).toEqual(['abc'])
+```
+
+```ts
+const lexer = createLexer((_chunk, metadata) => metadata, ['a', 'a'], ['b', 'b'])
+
+const result = lexer('aabb')
+
+expect(result).toEqual(['a', 'a', 'b', 'b'])
+```
+
+```ts
+const lexer = createLexer(
+  (chunk, metadata) => `${metadata}:${chunk}`,
+  ['open', '(', { push: 'inner' }],
+  ['word', /\w+/, { in: 'inner' }],
+  ['close', ')', { in: 'inner', pop: true }]
+)
+
+const result = lexer('a(b)c)')
+
+expect(result).toEqual(['undefined:a', 'open:(', 'word:b', 'close:)', 'undefined:c)'])
+```
+
+```ts
+const lexer = createLexer(
+  (chunk, metadata) => `${metadata}:${chunk}`,
+  ['open', '{', { in: ['root', 'nested'], push: 'nested' }],
+  ['close', '}', { in: 'nested', pop: true }]
+)
+
+const result = lexer('{{}}}')
+
+expect(result).toEqual(['open:{', 'open:{', 'close:}', 'close:}', 'undefined:}'])
+```
+
+```ts
+const lexer = createLexer((chunk, metadata) => `${metadata}:${chunk}`, ['a', 'a'], ['b', /(?<=a)b/])
+
+const result = lexer('abcb')
+
+expect(result).toEqual(['a:a', 'b:b', 'undefined:cb'])
+```
+
+```ts
+const lexer = createLexer((chunk, metadata) => `${metadata}:${chunk}`, ['x', /x/y], ['y', 'y'])
+
+const result = lexer('xyx.x')
+
+expect(result).toEqual(['x:x', 'y:y', 'x:x', 'undefined:.x'])
+```
+
+```ts
+const lexer = createLexer((chunk, metadata) => `${metadata}:${chunk}`, ['digits', /\d*/])
+
+const result = lexer('ab12')
+
+expect(result).toEqual(['undefined:ab', 'digits:12'])
+```
+
+### h
+
+```ts
+const h: {
+  <T extends keyof HTMLElementTagNameMap>(tag: T, ...args: HArgs1[]): HTMLElementTagNameMap[T]
+  <N extends Node>(node: N, ...args: HArgs1[]): N
+  (tagOrNode: string | Node, ...args: HArgs1[]): Node
+}
+```
+
+A lightweight _HyperScript_-style helper for creating and modifying `HTMLElement`s (see also [`s`](#s)).
+
+#### tagOrNode
+
+If a `string`, it is treated as the tag name for a new element.
+If a `Node`, that node is modified in place.
+
+#### args
+
+Additional arguments processed as follows:
+
+- `Object`: maps attributes/properties.
+  - Keys starting with `$` set element properties (without the `$` prefix); if the value is a plain object, it is shallow-merged into the existing property instead of replacing it (useful e.g. for `$style`).
+  - Other keys set attributes: a key prefixed with `xlink:` sets the attribute via `setAttributeNS` in the XLink namespace; any other key (without a colon) sets it via `setAttribute`.
+    A value of `true` sets an empty attribute (e.g. `checked=""`), a value of `false` removes the attribute.
+- `null`/`undefined`: ignored.
+- `Node`: appended as a child.
+- `string`/`number`: converted to a `Text` node and appended.
+- [`HArgs`](#HArgs) array: processed recursively (creates or modifies a child node and appends it).
+
+#### Returns
+
+The created `HTMLElement` or the modified node.
+
+#### Usage Examples
+
+```ts
+const b = h('b')
+
+expect(b.outerHTML).toBe('<b></b>')
+
+const i = h('i', 'text')
+
+h(b, i)
+
+expect(i.outerHTML).toBe('<i>text</i>')
+
+expect(b.outerHTML).toBe('<b><i>text</i></b>')
+
+h(i, { $className: 'some class' })
+
+expect(i.outerHTML).toBe('<i class="some class">text</i>')
+
+expect(b.outerHTML).toBe('<b><i class="some class">text</i></b>')
+```
+
+```ts
+expect(h('span', 'text').outerHTML).toBe('<span>text</span>')
+
+expect(h('span', { $innerText: 'text' }).outerHTML).toBe('<span>text</span>')
+
+expect(h('span', '42').outerHTML).toBe('<span>42</span>')
+
+expect(h('span', 42).outerHTML).toBe('<span>42</span>')
+```
+
+```ts
+expect(h('div', { style: 'margin:0;padding:0' }).outerHTML).toBe('<div style="margin:0;padding:0"></div>')
+
+expect(h('div', { $style: 'margin:0;padding:0' }).outerHTML).toBe('<div style="margin: 0px; padding: 0px;"></div>')
+
+expect(h('div', { $style: { margin: 0, padding: 0 } }).outerHTML).toBe(
+  '<div style="margin: 0px; padding: 0px;"></div>'
+)
+```
+
+```ts
+const input1 = h('input', { value: 42 })
+const input2 = h('input', { $value: '42' })
+
+expect(input1.value).toBe('42')
+expect(input2.value).toBe('42')
+
+expect(input1.outerHTML).toBe('<input value="42">')
+expect(input2.outerHTML).toBe('<input>')
+```
+
+```ts
+const checkbox1 = h('input', {
+  type: 'checkbox',
+  checked: true,
+})
+
+const checkbox2 = h('input', {
+  type: 'checkbox',
+  $checked: true,
+})
+
+expect(checkbox1.checked).toBe(true)
+expect(checkbox2.checked).toBe(true)
+
+expect(checkbox1.outerHTML).toBe('<input type="checkbox" checked="">')
+
+expect(checkbox2.outerHTML).toBe('<input type="checkbox">')
+```
+
+```ts
+const div = h('div')
+
+expect(div.key).toBeUndefined()
+
+h(div, { $key: { one: 1 } })
+
+expect(div.key).toEqual({ one: 1 })
+
+h(div, { $key: { two: 2 } })
+
+expect(div.key).toEqual({ one: 1, two: 2 })
+```
+
+```ts
+const elemWithClass = h('div', { class: 'test' })
+
+expect(elemWithClass.getAttribute('class')).toBe('test')
+
+const elemWithText = h('div', 'initial')
+
+h(elemWithText, ' more')
+
+expect(elemWithText.outerHTML).toBe('<div>initial more</div>')
+
+const elemWithNested = h('div', ['span', 'hello'], ['b', 'world'])
+
+expect(elemWithNested.outerHTML).toBe('<div><span>hello</span><b>world</b></div>')
+```
+
+### monokai
+
+```ts
+const monokai: CNode
+```
+
+A Monokai-inspired color scheme for use with the [`c`](#c) helper and [`nanolightTs`](#nanolightTs) lexer.
+It styles `pre` and `code>span` elements with the class names produced by [`nanolightTs`](#nanolightTs) (with light, dark and print variants).
+
+#### Usage Examples
+
+```ts
+const style = h('style', c(monokai))
+const pre = h('pre', ['code', ...nanolightTs('const x = 42')])
+
+expect(style.textContent).toContain('code>span.keyword1{color:var(--keyword1)}')
+expect(style.textContent).toContain('@media only screen and (prefers-color-scheme: dark){:root{--bg:#2d2a2e;')
+expect(pre.outerHTML).toBe(
+  '<pre><code>' +
+    '<span class="keyword1">const</span> ' +
+    '<span class="identifier4">x</span> ' +
+    '<span class="operator">=</span> ' +
+    '<span class="number">42</span>' +
+    '</code></pre>'
+)
+```
+
+### nanolightTs
+
+```ts
+const nanolightTs: (code: string) => HArgs1[]
+```
+
+A TypeScript/JavaScript syntax highlighting lexer built using [`createLexer`](#createLexer).
+
+#### code
+
+The source code string to tokenize.
+
+#### Returns
+
+An array of [`HArgs1`](#HArgs1) elements suitable for rendering with [`h`](#h): plain `string`s for unrecognized text (e.g. whitespace) and `['span', { class }, chunk]` tuples for recognized tokens (class names are styled by [`monokai`](#monokai)).
+
+#### Usage Examples
+
+```ts
+const codeJs = 'const answerToLifeTheUniverseAndEverything = ' + "{ 42: 42 }['42'] /* 42 */"
+
+expect(nanolightTs(codeJs)).toEqual([
+  ['span', { class: 'keyword1' }, 'const'],
+  ' ',
+  ['span', { class: 'identifier4' }, 'answerToLifeTheUniverseAndEverything'],
+  ' ',
+  ['span', { class: 'operator' }, '='],
+  ' ',
+  ['span', { class: 'punctuation' }, '{'],
+  ' ',
+  ['span', { class: 'number' }, '42'],
+  ['span', { class: 'operator' }, ':'],
+  ' ',
+  ['span', { class: 'number' }, '42'],
+  ' ',
+  ['span', { class: 'punctuation' }, '}'],
+  ['span', { class: 'punctuation' }, '['],
+  ['span', { class: 'string' }, "'42'"],
+  ['span', { class: 'punctuation' }, ']'],
+  ' ',
+  ['span', { class: 'comment' }, '/* 42 */'],
+])
+```
+
+```ts
+const codeJs = 'const x = 42 // answer'
+
+expect(nanolightTs(codeJs)).toEqual([
+  ['span', { class: 'keyword1' }, 'const'],
+  ' ',
+  ['span', { class: 'identifier4' }, 'x'],
+  ' ',
+  ['span', { class: 'operator' }, '='],
+  ' ',
+  ['span', { class: 'number' }, '42'],
+  ' ',
+  ['span', { class: 'comment' }, '// answer'],
+])
+```
+
+```ts
+expect(nanolightTs('x = /a\\/b[/]c/gi.test(y) / 2')).toEqual([
+  ['span', { class: 'identifier4' }, 'x'],
+  ' ',
+  ['span', { class: 'operator' }, '='],
+  ' ',
+  ['span', { class: 'string' }, '/a\\/b[/]c/gi'],
+  ['span', { class: 'punctuation' }, '.'],
+  ['span', { class: 'identifier2' }, 'test'],
+  ['span', { class: 'punctuation' }, '('],
+  ['span', { class: 'identifier4' }, 'y'],
+  ['span', { class: 'punctuation' }, ')'],
+  ' ',
+  ['span', { class: 'operator' }, '/'],
+  ' ',
+  ['span', { class: 'number' }, '2'],
+])
+
+expect(nanolightTs('a / b / c')).toEqual([
+  ['span', { class: 'identifier4' }, 'a'],
+  ' ',
+  ['span', { class: 'operator' }, '/'],
+  ' ',
+  ['span', { class: 'identifier4' }, 'b'],
+  ' ',
+  ['span', { class: 'operator' }, '/'],
+  ' ',
+  ['span', { class: 'identifier4' }, 'c'],
+])
+
+expect(nanolightTs('return / x /')).toEqual([
+  ['span', { class: 'keyword1' }, 'return'],
+  ' ',
+  ['span', { class: 'string' }, '/ x /'],
+])
+```
+
+```ts
+expect(nanolightTs('`a ${b + `c ${ {d}.d }`} \\${e} $f`')).toEqual([
+  ['span', { class: 'string' }, '`a '],
+  ['span', { class: 'punctuation' }, '${'],
+  ['span', { class: 'identifier4' }, 'b'],
+  ' ',
+  ['span', { class: 'operator' }, '+'],
+  ' ',
+  ['span', { class: 'string' }, '`c '],
+  ['span', { class: 'punctuation' }, '${'],
+  ' ',
+  ['span', { class: 'punctuation' }, '{'],
+  ['span', { class: 'identifier4' }, 'd'],
+  ['span', { class: 'punctuation' }, '}'],
+  ['span', { class: 'punctuation' }, '.'],
+  ['span', { class: 'identifier4' }, 'd'],
+  ' ',
+  ['span', { class: 'punctuation' }, '}'],
+  ['span', { class: 'string' }, '`'],
+  ['span', { class: 'punctuation' }, '}'],
+  ['span', { class: 'string' }, ' \\${e} $f`'],
+])
+
+expect(nanolightTs('`${x}` / 2')).toEqual([
+  ['span', { class: 'string' }, '`'],
+  ['span', { class: 'punctuation' }, '${'],
+  ['span', { class: 'identifier4' }, 'x'],
+  ['span', { class: 'punctuation' }, '}'],
+  ['span', { class: 'string' }, '`'],
+  ' ',
+  ['span', { class: 'operator' }, '/'],
+  ' ',
+  ['span', { class: 'number' }, '2'],
+])
+```
+
+```ts
+expect(nanolightTs('"a // b" // c')).toEqual([
+  ['span', { class: 'string' }, '"a // b"'],
+  ' ',
+  ['span', { class: 'comment' }, '// c'],
+])
+
+expect(nanolightTs("'it\\'s' /* x")).toEqual([
+  ['span', { class: 'string' }, "'it\\'s'"],
+  ' ',
+  ['span', { class: 'comment' }, '/* x'],
+])
+```
+
+```ts
+expect(nanolightTs('0xFF + 1_000n + .5e-3')).toEqual([
+  ['span', { class: 'number' }, '0xFF'],
+  ' ',
+  ['span', { class: 'operator' }, '+'],
+  ' ',
+  ['span', { class: 'number' }, '1_000n'],
+  ' ',
+  ['span', { class: 'operator' }, '+'],
+  ' ',
+  ['span', { class: 'number' }, '.5e-3'],
+])
+```
+
+```ts
+expect(nanolightTs('a++ / 2 / b')).toEqual([
+  ['span', { class: 'identifier4' }, 'a'],
+  ['span', { class: 'operator' }, '++'],
+  ' ',
+  ['span', { class: 'operator' }, '/'],
+  ' ',
+  ['span', { class: 'number' }, '2'],
+  ' ',
+  ['span', { class: 'operator' }, '/'],
+  ' ',
+  ['span', { class: 'identifier4' }, 'b'],
+])
+
+expect(nanolightTs('x?.5:a?.b')).toEqual([
+  ['span', { class: 'identifier4' }, 'x'],
+  ['span', { class: 'operator' }, '?'],
+  ['span', { class: 'number' }, '.5'],
+  ['span', { class: 'operator' }, ':'],
+  ['span', { class: 'identifier4' }, 'a'],
+  ['span', { class: 'punctuation' }, '?.'],
+  ['span', { class: 'identifier4' }, 'b'],
+])
+```
+
+```ts
+expect(nanolightTs('p.catch(obj.in, ...this)')).toEqual([
+  ['span', { class: 'identifier4' }, 'p'],
+  ['span', { class: 'punctuation' }, '.'],
+  ['span', { class: 'identifier2' }, 'catch'],
+  ['span', { class: 'punctuation' }, '('],
+  ['span', { class: 'identifier4' }, 'obj'],
+  ['span', { class: 'punctuation' }, '.'],
+  ['span', { class: 'identifier4' }, 'in'],
+  ['span', { class: 'punctuation' }, ','],
+  ' ',
+  ['span', { class: 'operator' }, '...'],
+  ['span', { class: 'keyword1' }, 'this'],
+  ['span', { class: 'punctuation' }, ')'],
+])
+```
+
+```ts
+expect(nanolightTs('#!/usr/bin/env bun\n@sealed class A { #x = 1 }')).toEqual([
+  ['span', { class: 'comment' }, '#!/usr/bin/env bun'],
+  '\n',
+  ['span', { class: 'identifier2' }, '@sealed'],
+  ' ',
+  ['span', { class: 'keyword1' }, 'class'],
+  ' ',
+  ['span', { class: 'identifier1' }, 'A'],
+  ' ',
+  ['span', { class: 'punctuation' }, '{'],
+  ' ',
+  ['span', { class: 'identifier4' }, '#x'],
+  ' ',
+  ['span', { class: 'operator' }, '='],
+  ' ',
+  ['span', { class: 'number' }, '1'],
+  ' ',
+  ['span', { class: 'punctuation' }, '}'],
+])
+```
+
+### rwd
+
+```ts
+const rwd: (
+  root: CNode,
+  selector: string,
+  cellWidthPx: number,
+  cellHeightPx: number,
+  ...specs: [number, number?, number?][]
+) => void
+```
+
+A responsive web design helper that generates CSS rules for a grid-like layout of floating elements.
+It modifies `root` in place: it sets base styles for `selector` and adds a `@media(min-width:…px)` rule for each breakpoint.
+
+#### root
+
+The CSS root object to populate (see [`c`](#c)).
+
+#### selector
+
+The CSS selector for the grid item.
+
+#### cellWidthPx
+
+The base cell width in pixels.
+
+#### cellHeightPx
+
+The base cell height in pixels.
+
+#### specs
+
+An array of breakpoint specifications, each a tuple of:
+
+- `maxWidth`: number of cells per row; the breakpoint is `min-width: cellWidthPx * maxWidth` (`1` modifies the base rule).
+- `width` (optional, default `1`): number of horizontal cells the element spans.
+- `height` (optional, default `1`): number of vertical cells the element spans.
+
+#### Usage Examples
+
+```ts
+const style: CNode = {
+  body: {
+    margin: 0,
+  },
+  '.r6': {
+    border: 'solid red 1px',
+    '.no-border': {
+      border: 'none',
+    },
+  },
+}
+
+rwd(style, '.r6', 200, 50, [6], [3], [1, 1, 2])
+
+expect(style).toEqual({
+  body: {
+    margin: 0,
+  },
+  '.r6': {
+    border: 'solid red 1px',
+    '.no-border': {
+      border: 'none',
+    },
+    'box-sizing': 'border-box',
+    display: 'block',
+    float: 'left',
+    width: '100%',
+    height: '100px',
+  },
+  '@media(min-width:600px)': {
+    '.r6': {
+      width: 'calc(100% / 3)',
+      height: '50px',
+    },
+  },
+  '@media(min-width:1200px)': {
+    '.r6': {
+      width: 'calc(50% / 3)',
+      height: '50px',
+    },
+  },
+})
+```
+
+### s
+
+```ts
+const s: {
+  <T extends keyof SVGElementTagNameMap>(tag: T, ...args: HArgs1[]): SVGElementTagNameMap[T]
+  <N extends Node>(node: N, ...args: HArgs1[]): N
+  (tagOrNode: string | Node, ...args: HArgs1[]): Node
+}
+```
+
+A lightweight _HyperScript_-style helper for creating and modifying `SVGElement`s (see also [`h`](#h)).
+
+#### tagOrNode
+
+If a `string`, it is treated as the tag name for a new element.
+If a `Node`, that node is modified in place.
+
+#### args
+
+Additional arguments processed as follows:
+
+- `Object`: maps attributes/properties.
+  - Keys starting with `$` set element properties (without the `$` prefix); if the value is a plain object, it is shallow-merged into the existing property instead of replacing it.
+  - Other keys set attributes: a key prefixed with `xlink:` sets the attribute via `setAttributeNS` in the XLink namespace; any other key (without a colon) sets it via `setAttribute`.
+    A value of `true` sets an empty attribute (e.g. `checked=""`), a value of `false` removes the attribute.
+- `null`/`undefined`: ignored.
+- `Node`: appended as a child.
+- `string`/`number`: converted to a `Text` node and appended.
+- [`HArgs`](#HArgs) array: processed recursively (creates or modifies a child node and appends it).
+
+#### Returns
+
+The created `SVGElement` or the modified node.
+
+#### Usage Examples
+
+```ts
+const svg = s('svg', { 'xlink:href': true })
+
+expect(svg.getAttributeNS('http://www.w3.org/1999/xlink', 'href')).toBe('')
+```
+
+```ts
+const svg = s('svg', { 'xlink:href': false })
+
+expect(svg.getAttributeNS('http://www.w3.org/1999/xlink', 'href')).toBeNull()
+```
+
+```ts
+const svg = s('svg', { 'xlink:href': 'http://example.com' })
+
+expect(svg.getAttributeNS('http://www.w3.org/1999/xlink', 'href')).toBe('http://example.com')
+```
+
+```ts
+const svg = s('svg', { 'xlink:title': 42 })
+
+expect(svg.getAttributeNS('http://www.w3.org/1999/xlink', 'title')).toBe('42')
+```
+
+### svgUse
+
+```ts
+const svgUse: (id: string, ...args: HArgs1[]) => SVGSVGElement
+```
+
+Shorthand for creating an `<svg>` element with a `<use>` child referencing a symbol (e.g. an icon) by ID.
+
+Equivalent to:
+
+```ts
+s('svg', ['use', { 'xlink:href': '#' + id }], ...args)
+```
+
+#### id
+
+The ID of the symbol to reference (without the `#` prefix).
+
+#### args
+
+Additional arguments passed to the outer `<svg>` element.
+
+#### Returns
+
+An `SVGSVGElement` containing a `<use>` element.
+
+#### Usage Examples
+
+```ts
+const svg = svgUse('icon-home')
+
+expect(svg.children.length).toBe(1)
+
+const useElement = svg.children[0]
+
+expect(useElement.getAttributeNS('http://www.w3.org/1999/xlink', 'href')).toBe('#icon-home')
+
+const svgWithViewBox = svgUse('icon-star', { viewBox: '0 0 24 24' })
+
+expect(svgWithViewBox.getAttribute('viewBox')).toBe('0 0 24 24')
+
+const useViewBox = svgWithViewBox.children[0]
+
+expect(useViewBox.getAttributeNS('http://www.w3.org/1999/xlink', 'href')).toBe('#icon-star')
+
+const svgWithClass = svgUse('icon-menu', { class: 'icon-btn' })
+
+expect(svgWithClass.getAttribute('class')).toBe('icon-btn')
+
+expect(svgWithClass.children.length).toBe(1)
+
+const useClass = svgWithClass.children[0]
+
+expect(useClass.getAttributeNS('http://www.w3.org/1999/xlink', 'href')).toBe('#icon-menu')
+
+const svgWithMultipleAttrs = svgUse('icon-settings', { width: 24, height: 24, class: 'icon' })
+
+expect(svgWithMultipleAttrs.getAttribute('width')).toBe('24')
+
+expect(svgWithMultipleAttrs.getAttribute('height')).toBe('24')
+
+expect(svgWithMultipleAttrs.getAttribute('class')).toBe('icon')
+
+const useMultiple = svgWithMultipleAttrs.children[0]
+
+expect(useMultiple.getAttributeNS('http://www.w3.org/1999/xlink', 'href')).toBe('#icon-settings')
+```
+
+## License
+
+The MIT License (MIT)
+
+Copyright (c) 2016+ Jackens
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.