@jackens/nnn 2025.12.10 → 2025.12.11

package/nnn.d.ts

@@ -1,20 +1,34 @@
-/** Argument type for the `h` and `s` helpers. */
+/**
+ * Single argument type for the {@link h} and {@link s} helpers.
+ */
 export type HArgs1 = Record<PropertyKey, unknown> | null | undefined | Node | string | number | HArgs;
-/** Argument type for the `h` and `s` helpers. */
+/**
+ * Tuple argument type for the {@link h} and {@link s} helpers.
+ */
 export type HArgs = [string | Node, ...HArgs1[]];
 /**
- * A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper for creating and modifying `HTMLElement`s (see also `s`).
+ * A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper
+ * for creating and modifying `HTMLElement`s (see also {@link s}).
+ *
+ * @param tag_or_node
+ *
+ * If a `string`, it is treated as the tag name for a new element.
+ * If a `Node`, that node is modified in place.
  *
- * - If the first argument is a `string`, it is treated as the tag name to create.
- * - If the first argument is a `Node`, that node is modified.
- * - Object arguments map attributes/properties:
- *   - Keys starting with `$` set element properties (without `$`).
- *   - Other keys set attributes via `setAttribute`.
- *   - Attributes with value `false` are removed via `removeAttribute`.
- * - `null` / `undefined` are ignored.
- * - `Node` arguments are appended.
- * - `string` / `number` arguments become `Text` nodes.
- * - `HArgs` arrays are processed recursively.
+ * @param args
+ *
+ * Additional arguments processed as follows:
+ * - `Object`: Maps attributes/properties. Keys starting with `$` set element properties
+ *   (without the `$` prefix); other keys set attributes via `setAttribute`.
+ *   A value of `false` removes the attribute.
+ * - `null` / `undefined`: Ignored.
+ * - `Node`: Appended as a child.
+ * - `string` / `number`: Converted to a `Text` node and appended.
+ * - {@link HArgs} array: Processed recursively.
+ *
+ * @returns
+ *
+ * The created or modified `HTMLElement`.
  */
 export declare const h: {
     <T extends keyof HTMLElementTagNameMap>(tag: T, ...args1: HArgs1[]): HTMLElementTagNameMap[T];
@@ -22,122 +36,418 @@ export declare const h: {
     (tag_or_node: string | Node, ...args1: HArgs1[]): Node;
 };
 /**
- * A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper for creating and modifying `SVGElement`s (see also `h`).
+ * A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper
+ * for creating and modifying `SVGElement`s (see also {@link h}).
+ *
+ * @param tag_or_node
+ *
+ * If a `string`, it is treated as the tag name for a new element.
+ * If a `Node`, that node is modified in place.
  *
- * - If the first argument is a `string`, it is treated as the tag name to create.
- * - If the first argument is a `Node`, that node is modified.
- * - Object arguments map attributes/properties:
- *   - Keys starting with `$` set element properties (without `$`).
- *   - Other keys set attributes via `setAttributeNS`.
- *   - Attributes with value `false` are removed via `removeAttributeNS`.
- * - `null` / `undefined` are ignored.
- * - `Node` arguments are appended.
- * - `string` / `number` arguments become `Text` nodes.
- * - `HArgs` arrays are processed recursively.
+ * @param args
+ *
+ * Additional arguments processed as follows:
+ * - `Object`: Maps attributes/properties. Keys starting with `$` set element properties
+ *   (without the `$` prefix); other keys set attributes via `setAttributeNS`.
+ *   A value of `false` removes the attribute.
+ * - `null` / `undefined`: Ignored.
+ * - `Node`: Appended as a child.
+ * - `string` / `number`: Converted to a `Text` node and appended.
+ * - {@link HArgs} array: Processed recursively.
+ *
+ * @returns
+ *
+ * The created or modified `SVGElement`.
  */
 export declare const s: {
     <T extends keyof SVGElementTagNameMap>(tag: T, ...args1: HArgs1[]): SVGElementTagNameMap[T];
     <N extends Node>(node: N, ...args1: HArgs1[]): N;
     (tag_or_node: string | Node, ...args1: HArgs1[]): Node;
 };
-/** Shorthand for: `s('svg', ['use', { 'xlink:href': '#' + id }], ...args)`. */
+/**
+ * Shorthand for creating an SVG element with a `<use>` child referencing an icon by ID.
+ *
+ * Equivalent to: `s('svg', ['use', { 'xlink:href': '#' + id }], ...args)`.
+ *
+ * @param id
+ *
+ * The ID of the symbol to reference (without the `#` prefix).
+ *
+ * @param args
+ *
+ * Additional arguments passed to the outer `<svg>` element.
+ *
+ * @returns
+ *
+ * An `SVGSVGElement` containing a `<use>` element.
+ */
 export declare const svg_use: (id: string, ...args: HArgs1[]) => SVGSVGElement;
 /**
- * Generic syntax highlighting helper (see also `nanolight_ts`).
+ * A helper for building simple tokenizers (see also {@link nanolight_ts}).
+ *
+ * @param decorator
+ *
+ * A function that wraps each matched chunk. It receives the matched text (`chunk`)
+ * and optionally the `metadata` associated with the pattern that produced the match.
+ * For unmatched text between patterns, `metadata` is `undefined`.
+ *
+ * @param specs
+ *
+ * An array of tuples `[metadata, pattern]` where:
+ * - `metadata`: Arbitrary data (e.g., a CSS class name) passed to `decorator` when the pattern matches.
+ * - `pattern`: A `string` or `RegExp` to match against the input.
+ *
+ * @returns
+ *
+ * A tokenizer function that accepts a code string and returns an array of decorated tokens.
+ *
+ * @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.
+ */
+export declare const new_tokenizer: <M, T>(decorator: (chunk: string, metadata?: M) => T, ...specs: [M, string | RegExp][]) => (code: string) => T[];
+/**
+ * A TypeScript/JavaScript syntax highlighting tokenizer built using {@link new_tokenizer}.
  *
- * - `decorator` is a function that wraps each matched chunk.
- *   It receives the matched text (`chunk`) and optionally the `metadata` associated with the pattern that produced the match.
- *   For unmatched text between patterns, `metadata` is `undefined`.
- * - `rules` is an array of tuples `[metadata, pattern]` where:
- *   - `metadata`: data (e.g. CSS class name) passed to the `decorator` when the pattern matches.
- *   - `pattern`: a `string` or `RegExp` to match against the code.
+ * @param code
  *
- * Matching rules:
- * - For any two matches at different positions, the one starting earlier takes precedence.
- * - For any two matches at the same position, the longer one takes precedence.
- * - For any two matches at the same position and of the same length, the one defined earlier takes precedence.
+ * The source code string to tokenize.
+ *
+ * @returns
+ *
+ * An array of {@link HArgs1} elements suitable for rendering with {@link h} or {@link s}.
  */
-export declare const nanolight: <M, T>(decorator: (chunk: string, metadata?: M) => T, ...rules: [M, string | RegExp][]) => (code: string) => T[];
-/** TypeScript syntax highlighting helper (built on `nanolight`). */
 export declare const nanolight_ts: (code: string) => HArgs1[];
-/** Applies Polish‑specific typographic corrections. */
+/**
+ * Applies Polish-specific typographic corrections to a DOM subtree.
+ *
+ * This function prevents orphaned conjunctions (single-letter words like “a”, “i”, “o”, “u”, “w”, “z”)
+ * from appearing at the end of a line by wrapping them with the following word in a non-breaking span.
+ * It also inserts zero-width spaces after slashes and dots to allow line breaks.
+ *
+ * @param node
+ *
+ * The root DOM node to process. All descendant text nodes are corrected recursively,
+ * except those inside `IFRAME`, `NOSCRIPT`, `PRE`, `SCRIPT`, `STYLE`, or `TEXTAREA` elements.
+ */
 export declare const fix_typography: (node: Node) => void;
-/** Argument type for the `c` helper. */
+/**
+ * Represents a CSS rule node for the {@link c} helper. Keys are CSS properties or nested selectors.
+ */
 export type CNode = {
     [attribute_or_selector: string]: string | number | CNode | undefined;
 };
-/** Argument type for the `c` helper. */
+/**
+ * Represents the root CSS object for the {@link c} helper. Keys are top-level selectors or at-rules.
+ */
 export type CRoot = Record<PropertyKey, CNode>;
 /**
- * A minimal JS-to-CSS (CSS‑in‑JS) helper.
+ * A minimal CSS-in-JS helper that converts a JavaScript object hierarchy into a CSS string.
  *
- * The `root` object describes a hierarchy of CSS rules.
+ * @param root
  *
- * - Keys whose values are not objects are treated as CSS property names; their values become property values. The concatenation of parent keys produces a selector.
- * - For every key, the substring from the splitter (default: `$$`) to the end is ignored (e.g. `src$$1` → `src`, `@font-face$$1` → `@font-face`).
- * - In property keys, uppercase letters are converted to lowercase and prefixed with `-` (e.g. `fontFamily` → `font-family`); underscores are converted to `-` (e.g. `font_family` → `font-family`).
- * - Commas inside selector keys cause them to expand into multiple selectors (e.g. `{div:{margin:1,'.a,.b,.c':{margin:2}}}` → `div{margin:1}div.a,div.b,div.c{margin:2}`).
- * - Top-level keys beginning with `@` (at-rules) are not concatenated with parent keys.
+ * An object describing CSS rules.
+ * Keys are selectors or at-rules; values are either CSS property values or nested rule objects.
+ *
+ * @param 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.
+ *
+ * @remarks
+ *
+ * - Keys whose values are primitives (`string` | `number`) are treated as CSS properties.
+ * - In property keys, uppercase letters become lowercase with a `-` prefix (e.g., `fontFamily` → `font-family`);
+ *   underscores become hyphens (e.g., `font_family` → `font-family`).
+ * - Comma-separated selector keys expand into multiple selectors
+ *   (e.g., `{ div: { '.a,.b': { margin: 1 } } }` → `div.a,div.b{margin:1}`).
+ * - Top-level keys starting with `@` (at-rules) are not concatenated with child selectors.
  */
 export declare const c: (root: CRoot, splitter?: string) => string;
 /**
- * A responsive‑web‑design helper that generates CSS rules for a grid-like layout.
+ * A responsive web design helper that generates CSS rules for a grid-like layout.
+ *
+ * @param root
+ *
+ * The CSS root object to populate (see {@link c}).
+ *
+ * @param selector
+ *
+ * The CSS selector for the grid item.
+ *
+ * @param cell_width_px
  *
- * - `root` and `selector` specify where to apply the generated rules (see `c`).
- * - `cell_width_px` and `cell_height_px` specify the base cell dimensions in pixels.
- * - Each entry in `specs` is a tuple of:
- *   - `max_width`: maximum number of cells in a row (viewport width breakpoint).
- *   - `width` (optional, default: `1`): number of cells occupied by the element.
- *   - `height` (optional, default: `1`): number of cells the element occupies vertically.
+ * The base cell width in pixels.
+ *
+ * @param cell_height_px
+ *
+ * The base cell height in pixels.
+ *
+ * @param specs
+ *
+ * An array of breakpoint specifications, each a tuple of:
+ * - `max_width`: Maximum number of cells per row (defines the viewport breakpoint).
+ * - `width` (optional, default `1`): Number of horizontal cells the element spans.
+ * - `height` (optional, default `1`): Number of vertical cells the element spans.
  */
 export declare const rwd: (root: CRoot, selector: string, cell_width_px: number, cell_height_px: number, ...specs: [number, number?, number?][]) => void;
-/** Argument type accepted by the `escape_values` and `escape` helpers. */
+/**
+ * A map from value constructors (or `null`/`undefined`) to escape functions.
+ *
+ * Used by {@link escape_values} and {@link escape}.
+ */
 export type EscapeMap = Map<unknown, (value?: unknown) => string>;
-/** Escapes array `values` using the provided `escape_map`. */
+/**
+ * Escapes an array of values using the provided escape map.
+ *
+ * @param escape_map
+ *
+ * A map where keys are constructors (e.g., `String`, `Number`) and values are escape functions.
+ *
+ * @param values
+ *
+ * The array of values to escape.
+ *
+ * @returns
+ *
+ * An array of escaped strings.
+ */
 export declare const escape_values: (escape_map: EscapeMap, values: unknown[]) => string[];
-/** Escapes interpolated template `values` using the provided `escape_map`. */
+/**
+ * Escapes interpolated values in a tagged template literal using the provided escape map.
+ *
+ * @param escape_map
+ *
+ * A map where keys are constructors and values are escape functions.
+ *
+ * @param template
+ *
+ * The template strings array from the tagged template.
+ *
+ * @param values
+ *
+ * The interpolated values to escape.
+ *
+ * @returns
+ *
+ * The resulting string with all interpolated values escaped.
+ */
 export declare const escape: (escape_map: EscapeMap, template: TemplateStringsArray, ...values: unknown[]) => string;
-/** Chooses the appropriate Polish noun form based on a numeric value. */
+/**
+ * Returns the appropriate Polish noun form based on a numeric value.
+ *
+ * Polish has three plural forms depending on the number:
+ * - Singular: used for exactly 1.
+ * - “Plural 2-4”: used for 2, 3, 4, 22, 23, 24, etc. (but not 12, 13, 14).
+ * - “Plural 5+”: used for 0, 5–21, 25–31, etc.
+ *
+ * @param singular
+ *
+ * The singular form (e.g., ”auto” for “car”).
+ *
+ * @param plural_2
+ *
+ * The form for 2, 3, 4 (e.g., “auta”).
+ *
+ * @param plural_5
+ *
+ * The form for 5+ (e.g., “aut”).
+ *
+ * @param value
+ *
+ * The numeric value to evaluate.
+ *
+ * @returns
+ *
+ * The appropriate noun form for the given value.
+ */
 export declare const pl_ural: (singular: string, plural_2: string, plural_5: string, value: number) => string;
 /**
  * Generates a UUID v1 (time-based) identifier.
  *
- * - Optional `node` must match `/^[0-9a-f]*$/`; it is trimmed to the last 12 characters and left-padded with zeros.
+ * @param date
+ *
+ * The date to use for the timestamp portion (default: current date/time).
+ *
+ * @param node
+ *
+ * A hexadecimal `string` for the node portion (default: random).
+ * Must match `/^[0-9a-f]*$/`; it is trimmed to the last 12 characters and left-padded with zeros if shorter.
+ *
+ * @returns
+ *
+ * A UUID v1 `string` in the standard format `xxxxxxxx-xxxx-1xxx-xxxx-xxxxxxxxxxxx`.
  */
 export declare const uuid_v1: (date?: Date, node?: string) => string;
 /**
- * `JSON.parse` with “JavaScript turned on”.
+ * Parses JSON with support for handler-based value transformation (“JavaScript ON”).
  *
- * Objects having *exactly* one property whose name exists in `handlers`, i.e.:
+ * Objects with exactly one property whose key exists in `handlers` and whose value is an array
+ * are replaced by invoking the corresponding handler with the array elements as arguments.
  *
- * ```js
- * { "«handler_name»": [«params»] }
- * ```
+ * @param handlers
  *
- * are replaced with:
+ * An object mapping handler names to functions.
  *
- * ```js
- * handlers['«handler_name»'](...«params»)
- * ```
+ * @param text
+ *
+ * The JSON string to parse.
+ *
+ * @returns
+ *
+ * The parsed value with handler substitutions applied.
  */
 export declare const js_on_parse: (handlers: Record<PropertyKey, Function>, text: string) => any;
-/** Checks whether the argument is an array. */
+/**
+ * Checks whether the argument is an array.
+ *
+ * @param arg
+ *
+ * The value to check.
+ *
+ * @returns
+ *
+ * `true` if `arg` is an array, `false` otherwise.
+ */
 export declare const is_array: (arg: unknown) => arg is unknown[];
-/** Checks whether the argument is a finite number (excluding `±Infinity` and `NaN`). */
+/**
+ * Checks whether the argument is a finite number (excludes `±Infinity` and `NaN`).
+ *
+ * @param arg
+ *
+ * The value to check.
+ *
+ * @returns
+ *
+ * `true` if `arg` is a finite number, `false` otherwise.
+ */
 export declare const is_finite_number: (arg: unknown) => arg is number;
-/** Checks whether the argument is a number. */
+/**
+ * Checks whether the argument is of type `number` (includes `NaN` and `±Infinity`).
+ *
+ * @param arg
+ *
+ * The value to check.
+ *
+ * @returns
+ *
+ * `true` if `typeof arg === 'number'`, `false` otherwise.
+ */
 export declare const is_number: (arg: unknown) => arg is number;
-/** Checks whether the argument is a plain object record. */
+/**
+ * Checks whether the argument is a plain object (not `null` and not an array).
+ *
+ * @param arg
+ *
+ * The value to check.
+ *
+ * @returns
+ *
+ * `true` if `arg` is a plain object, `false` otherwise.
+ */
 export declare const is_record: (arg: unknown) => arg is Record<PropertyKey, unknown>;
-/** Checks whether the argument is a string. */
+/**
+ * Checks whether the argument is a string.
+ *
+ * @param arg
+ *
+ * The value to check.
+ *
+ * @returns
+ *
+ * `true` if `typeof arg === 'string'`, `false` otherwise.
+ */
 export declare const is_string: (arg: unknown) => arg is string;
-/** A replacement for the `in` operator (not to be confused with `for-in`). */
+/**
+ * Checks whether an object has the specified key as its own property.
+ *
+ * A null-safe wrapper around `Object.hasOwn`.
+ *
+ * @param ref
+ *
+ * The object to check.
+ *
+ * @param key
+ *
+ * The property key to look for.
+ *
+ * @returns
+ *
+ * `true` if `ref` is not nullish and has `key` as an own property, `false` otherwise.
+ */
 export declare const has_own: (ref: unknown, key: unknown) => boolean;
-/** A `Proxy`-based helper that safely creates nested structures on access and allows deep assignment without guards. */
+/**
+ * A Proxy-based helper for auto-vivification of nested object structures.
+ *
+ * Accessing any property on the returned proxy automatically creates an empty object if the property does not exist,
+ * allowing deep assignments without explicit null checks.
+ *
+ * @param ref
+ *
+ * The root object to wrap.
+ *
+ * @returns
+ *
+ * A proxy that auto-creates nested objects on property access.
+ */
 export declare const pro: (ref: unknown) => any;
-/** A tiny CSV parsing helper. */
+/**
+ * Parses a CSV string into a two-dimensional array of strings.
+ *
+ * Supports quoted fields with escaped double quotes (`""`). Carriage returns are normalized.
+ *
+ * @param csv
+ *
+ * The CSV string to parse.
+ *
+ * @param separator
+ *
+ * The field delimiter (default: `','`).
+ *
+ * @returns
+ *
+ * A 2D array where each inner array represents a row of fields.
+ */
 export declare const csv_parse: (csv: string, separator?: string) => string[][];
-/** Runtime implementation of TypeScript’s `Pick` (see also `omit`). */
+/**
+ * Creates a new object containing only the specified keys from the source object.
+ *
+ * A runtime equivalent of TypeScript’s `Pick<T, K>` utility type. See also {@link omit}.
+ *
+ * @param ref
+ *
+ * The source object.
+ *
+ * @param keys
+ *
+ * An array of keys to include in the result.
+ *
+ * @returns
+ *
+ * A new object with only the specified keys.
+ */
 export declare const pick: <T, K extends keyof T>(ref: T, keys: K[]) => Pick<T, K>;
-/** Runtime implementation of TypeScript’s `Omit` (see also `pick`). */
+/**
+ * Creates a new object excluding the specified keys from the source object.
+ *
+ * A runtime equivalent of TypeScript’s `Omit<T, K>` utility type. See also {@link pick}.
+ *
+ * @param ref
+ *
+ * The source object.
+ *
+ * @param keys
+ *
+ * An array of keys to exclude from the result.
+ *
+ * @returns
+ *
+ * A new object without the specified keys.
+ */
 export declare const omit: <T, K extends keyof T>(ref: T, keys: unknown[]) => Omit<T, K>;

package/nnn.js

@@ -60,13 +60,13 @@ var _h = (namespace_uri) => {
 var h = _h();
 var s = _h("http://www.w3.org/2000/svg");
 var svg_use = (id, ...args) => s("svg", ["use", { "xlink:href": "#" + id }], ...args);
-var nanolight = (decorator, ...rules) => (code) => {
+var new_tokenizer = (decorator, ...specs) => (code) => {
   const result = [];
   while (code.length > 0) {
     let best_metadata;
     let best_index = Infinity;
     let best_chunk = "";
-    for (const [metadata, pattern] of rules) {
+    for (const [metadata, pattern] of specs) {
       let index = -1;
       let chunk = "";
       if (is_string(pattern) && pattern.length > 0) {
@@ -104,7 +104,7 @@ var PURPLE = "purple";
 var RED = "red";
 var WHITE = "white";
 var YELLOW = "yellow";
-var nanolight_ts = nanolight((chunk, name) => name != null ? ["span", { class: name }, chunk] : chunk, [YELLOW, /".*?"/], [YELLOW, /'.*?'/], [YELLOW, /`[\s\S]*?`/], [GREY, "("], [GREY, ")"], [GREY, ","], [GREY, "."], [GREY, ":"], [GREY, ";"], [GREY, "?"], [GREY, "["], [GREY, "]"], [GREY, "{"], [GREY, "}"], [GREY, /\/\*[\s\S]*?\*\//], [GREY, /\/\/.*?(?=\n)/], [RED, "!"], [RED, "!="], [RED, "!=="], [RED, "%"], [RED, "%="], [RED, "&&"], [RED, "&&="], [RED, "&"], [RED, "&="], [RED, "*"], [RED, "**"], [RED, "**="], [RED, "*="], [RED, "+"], [RED, "++"], [RED, "+="], [RED, "-"], [RED, "--"], [RED, "-="], [RED, "/"], [RED, "/="], [RED, ":"], [RED, "<"], [RED, "<<"], [RED, "<<="], [RED, "<="], [RED, "="], [RED, "=="], [RED, "==="], [RED, "=>"], [RED, ">"], [RED, ">="], [RED, ">>"], [RED, ">>="], [RED, ">>>"], [RED, ">>>="], [RED, "?"], [RED, "??"], [RED, "??="], [RED, "^"], [RED, "^="], [RED, "as"], [RED, "async"], [RED, "await"], [RED, "break"], [RED, "case"], [RED, "catch"], [RED, "class"], [RED, "const"], [RED, "continue"], [RED, "debugger"], [RED, "default"], [RED, "delete"], [RED, "do"], [RED, "else"], [RED, "export"], [RED, "extends"], [RED, "finally"], [RED, "for"], [RED, "from"], [RED, "function"], [RED, "function*"], [RED, "goto"], [RED, "if"], [RED, "import"], [RED, "in"], [RED, "instanceof"], [RED, "is"], [RED, "keyof"], [RED, "let"], [RED, "new"], [RED, "of"], [RED, "package"], [RED, "return"], [RED, "super"], [RED, "switch"], [RED, "this"], [RED, "throw"], [RED, "try"], [RED, "type"], [RED, "typeof"], [RED, "var"], [RED, "void"], [RED, "while"], [RED, "with"], [RED, "yield"], [RED, "yield*"], [RED, "|"], [RED, "|="], [RED, "||"], [RED, "||="], [RED, "~"], [RED, "~="], [PURPLE, "false"], [PURPLE, "Infinity"], [PURPLE, "NaN"], [PURPLE, "null"], [PURPLE, "true"], [PURPLE, "undefined"], [PURPLE, /0b[01_]+/], [PURPLE, /0o[01234567_]+/], [PURPLE, /0x[\dabcdef_]+/], [PURPLE, /[A-Z_$][A-Z0-9_$]+/], [PURPLE, /\d[\d_]*(\.[\d_]+)?(e[+-]?[\d_]+)?/], [BLUE, "any"], [BLUE, "bigint"], [BLUE, "boolean"], [BLUE, "eval"], [BLUE, "number"], [BLUE, "string"], [BLUE, "symbol"], [BLUE, "unknown"], [GREEN, /[$\w]+(?=\()/], [BLUE, /[A-Z][$\w]+/], [WHITE, /[$\w]+/]);
+var nanolight_ts = new_tokenizer((chunk, name) => name != null ? ["span", { class: name }, chunk] : chunk, [YELLOW, /".*?"/], [YELLOW, /'.*?'/], [YELLOW, /`[\s\S]*?`/], [GREY, "("], [GREY, ")"], [GREY, ","], [GREY, "."], [GREY, ":"], [GREY, ";"], [GREY, "?"], [GREY, "["], [GREY, "]"], [GREY, "{"], [GREY, "}"], [GREY, /\/\*[\s\S]*?\*\//], [GREY, /\/\/.*?(?=\n)/], [RED, "!"], [RED, "!="], [RED, "!=="], [RED, "%"], [RED, "%="], [RED, "&&"], [RED, "&&="], [RED, "&"], [RED, "&="], [RED, "*"], [RED, "**"], [RED, "**="], [RED, "*="], [RED, "+"], [RED, "++"], [RED, "+="], [RED, "-"], [RED, "--"], [RED, "-="], [RED, "/"], [RED, "/="], [RED, ":"], [RED, "<"], [RED, "<<"], [RED, "<<="], [RED, "<="], [RED, "="], [RED, "=="], [RED, "==="], [RED, "=>"], [RED, ">"], [RED, ">="], [RED, ">>"], [RED, ">>="], [RED, ">>>"], [RED, ">>>="], [RED, "?"], [RED, "??"], [RED, "??="], [RED, "^"], [RED, "^="], [RED, "as"], [RED, "async"], [RED, "await"], [RED, "break"], [RED, "case"], [RED, "catch"], [RED, "class"], [RED, "const"], [RED, "continue"], [RED, "debugger"], [RED, "default"], [RED, "delete"], [RED, "do"], [RED, "else"], [RED, "export"], [RED, "extends"], [RED, "finally"], [RED, "for"], [RED, "from"], [RED, "function"], [RED, "function*"], [RED, "goto"], [RED, "if"], [RED, "import"], [RED, "in"], [RED, "instanceof"], [RED, "is"], [RED, "keyof"], [RED, "let"], [RED, "new"], [RED, "of"], [RED, "package"], [RED, "return"], [RED, "super"], [RED, "switch"], [RED, "this"], [RED, "throw"], [RED, "try"], [RED, "type"], [RED, "typeof"], [RED, "var"], [RED, "void"], [RED, "while"], [RED, "with"], [RED, "yield"], [RED, "yield*"], [RED, "|"], [RED, "|="], [RED, "||"], [RED, "||="], [RED, "~"], [RED, "~="], [PURPLE, "false"], [PURPLE, "Infinity"], [PURPLE, "NaN"], [PURPLE, "null"], [PURPLE, "true"], [PURPLE, "undefined"], [PURPLE, /0b[01_]+/], [PURPLE, /0o[01234567_]+/], [PURPLE, /0x[\dabcdef_]+/], [PURPLE, /[A-Z_$][A-Z0-9_$]+/], [PURPLE, /\d[\d_]*(\.[\d_]+)?(e[+-]?[\d_]+)?/], [BLUE, "any"], [BLUE, "bigint"], [BLUE, "boolean"], [BLUE, "eval"], [BLUE, "number"], [BLUE, "string"], [BLUE, "symbol"], [BLUE, "unknown"], [GREEN, /[$\w]+(?=\()/], [BLUE, /[A-Z][$\w]+/], [WHITE, /[$\w]+/]);
 var TAGS_TO_SKIP = ["IFRAME", "NOSCRIPT", "PRE", "SCRIPT", "STYLE", "TEXTAREA"];
 var fix_typography = (node) => {
   const queue = [node];
@@ -208,7 +208,7 @@ var rwd = (root, selector, cell_width_px, cell_height_px, ...specs) => {
     node.height = `${cell_height_px * height}px`;
   }
 };
-var escape_values = (escape_map, values) => values.map((value) => (escape_map.get(value?.constructor) ?? escape_map.get(undefined))?.(value) ?? "");
+var escape_values = (escape_map, values) => values.map((value) => (value == null ? escape_map.get(value) : escape_map.get(value?.constructor))?.(value) ?? "");
 var escape = (escape_map, template, ...values) => String.raw(template, ...escape_values(escape_map, values));
 var pl_ural = (singular, plural_2, plural_5, value) => {
   const abs_value = Math.abs(value);
@@ -266,8 +266,8 @@ export {
   pl_ural,
   pick,
   omit,
+  new_tokenizer,
   nanolight_ts,
-  nanolight,
   js_on_parse,
   is_string,
   is_record,

package/package.json

@@ -38,5 +38,5 @@
   "name": "@jackens/nnn",
   "type": "module",
   "types": "nnn.d.ts",
-  "version": "2025.12.10"
+  "version": "2025.12.11"
 }

package/readme.md

@@ -28,33 +28,33 @@ import { «something» } from './node_modules/@jackens/nnn/nnn.js'
 
 ## Exports
 
-- [`CNode`](#CNode): Argument type for the [`c`](#c) helper.
-- [`CRoot`](#CRoot): Argument type for the [`c`](#c) helper.
-- [`EscapeMap`](#EscapeMap): Argument type accepted by the [`escape_values`](#escape_values) and [`escape`](#escape) helpers.
-- [`HArgs`](#HArgs): Argument type for the [`h`](#h) and [`s`](#s) helpers.
-- [`HArgs1`](#HArgs1): Argument type for the [`h`](#h) and [`s`](#s) helpers.
-- [`c`](#c): A minimal JS-to-CSS (CSS‑in‑JS) helper.
-- [`csv_parse`](#csv_parse): A tiny CSV parsing helper.
-- [`escape`](#escape): Escapes interpolated template `values` using the provided `escape_map`.
-- [`escape_values`](#escape_values): Escapes array `values` using the provided `escape_map`.
-- [`fix_typography`](#fix_typography): Applies Polish‑specific typographic corrections.
-- [`h`](#h): A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper for creating and modifying `HTMLElement`s (see also [`s`](#s)).
-- [`has_own`](#has_own): A replacement for the `in` operator (not to be confused with `for-in`).
+- [`CNode`](#CNode): Represents a CSS rule node for the [`c`](#c) helper. Keys are CSS properties or nested selectors.
+- [`CRoot`](#CRoot): Represents the root CSS object for the [`c`](#c) helper. Keys are top-level selectors or at-rules.
+- [`EscapeMap`](#EscapeMap): A map from value constructors (or `null`/`undefined`) to escape functions.
+- [`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.
+- [`c`](#c): A minimal CSS-in-JS helper that converts a JavaScript object hierarchy into a CSS string.
+- [`csv_parse`](#csv_parse): Parses a CSV string into a two-dimensional array of strings.
+- [`escape`](#escape): Escapes interpolated values in a tagged template literal using the provided escape map.
+- [`escape_values`](#escape_values): Escapes an array of values using the provided escape map.
+- [`fix_typography`](#fix_typography): Applies Polish-specific typographic corrections to a DOM subtree.
+- [`h`](#h): A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper
+- [`has_own`](#has_own): Checks whether an object has the specified key as its own property.
 - [`is_array`](#is_array): Checks whether the argument is an array.
-- [`is_finite_number`](#is_finite_number): Checks whether the argument is a finite number (excluding `±Infinity` and `NaN`).
-- [`is_number`](#is_number): Checks whether the argument is a number.
-- [`is_record`](#is_record): Checks whether the argument is a plain object record.
+- [`is_finite_number`](#is_finite_number): Checks whether the argument is a finite number (excludes `±Infinity` and `NaN`).
+- [`is_number`](#is_number): Checks whether the argument is of type `number` (includes `NaN` and `±Infinity`).
+- [`is_record`](#is_record): Checks whether the argument is a plain object (not `null` and not an array).
 - [`is_string`](#is_string): Checks whether the argument is a string.
-- [`js_on_parse`](#js_on_parse): `JSON.parse` with “JavaScript turned on”.
-- [`nanolight`](#nanolight): Generic syntax highlighting helper (see also [`nanolight_ts`](#nanolight_ts)).
-- [`nanolight_ts`](#nanolight_ts): TypeScript syntax highlighting helper (built on [`nanolight`](#nanolight)).
-- [`omit`](#omit): Runtime implementation of TypeScript’s `Omit` (see also [`pick`](#pick)).
-- [`pick`](#pick): Runtime implementation of TypeScript’s `Pick` (see also [`omit`](#omit)).
-- [`pl_ural`](#pl_ural): Chooses the appropriate Polish noun form based on a numeric value.
-- [`pro`](#pro): A `Proxy`-based helper that safely creates nested structures on access and allows deep assignment without guards.
-- [`rwd`](#rwd): A responsive‑web‑design helper that generates CSS rules for a grid-like layout.
-- [`s`](#s): A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper for creating and modifying `SVGElement`s (see also [`h`](#h)).
-- [`svg_use`](#svg_use): Shorthand for: `s('svg', ['use', { 'xlink:href': '#' + id }], ...args)`.
+- [`js_on_parse`](#js_on_parse): Parses JSON with support for handler-based value transformation (“JavaScript ON”).
+- [`nanolight_ts`](#nanolight_ts): A TypeScript/JavaScript syntax highlighting tokenizer built using [`new_tokenizer`](#new_tokenizer).
+- [`new_tokenizer`](#new_tokenizer): A helper for building simple tokenizers (see also [`nanolight_ts`](#nanolight_ts)).
+- [`omit`](#omit): Creates a new object excluding the specified keys from the source object.
+- [`pick`](#pick): Creates a new object containing only the specified keys from the source object.
+- [`pl_ural`](#pl_ural): Returns the appropriate Polish noun form based on a numeric value.
+- [`pro`](#pro): A Proxy-based helper for auto-vivification of nested object structures.
+- [`rwd`](#rwd): A responsive web design helper that generates CSS rules for a grid-like layout.
+- [`s`](#s): A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper
+- [`svg_use`](#svg_use): Shorthand for creating an SVG element with a `<use>` child referencing an icon by ID.
 - [`uuid_v1`](#uuid_v1): Generates a UUID v1 (time-based) identifier.
 
 ### CNode
@@ -65,7 +65,7 @@ type CNode = {
 };
 ```
 
-Argument type for the [`c`](#c) helper.
+Represents a CSS rule node for the [`c`](#c) helper. Keys are CSS properties or nested selectors.
 
 ### CRoot
 
@@ -73,7 +73,7 @@ Argument type for the [`c`](#c) helper.
 type CRoot = Record<PropertyKey, CNode>;
 ```
 
-Argument type for the [`c`](#c) helper.
+Represents the root CSS object for the [`c`](#c) helper. Keys are top-level selectors or at-rules.
 
 ### EscapeMap
 
@@ -81,7 +81,9 @@ Argument type for the [`c`](#c) helper.
 type EscapeMap = Map<unknown, (value?: unknown) => string>;
 ```
 
-Argument type accepted by the [`escape_values`](#escape_values) and [`escape`](#escape) helpers.
+A map from value constructors (or `null`/`undefined`) to escape functions.
+
+Used by [`escape_values`](#escape_values) and [`escape`](#escape).
 
 ### HArgs
 
@@ -89,7 +91,7 @@ Argument type accepted by the [`escape_values`](#escape_values) and [`escape`](#
 type HArgs = [string | Node, ...HArgs1[]];
 ```
 
-Argument type for the [`h`](#h) and [`s`](#s) helpers.
+Tuple argument type for the [`h`](#h) and [`s`](#s) helpers.
 
 ### HArgs1
 
@@ -97,7 +99,7 @@ Argument type for the [`h`](#h) and [`s`](#s) helpers.
 type HArgs1 = Record<PropertyKey, unknown> | null | undefined | Node | string | number | HArgs;
 ```
 
-Argument type for the [`h`](#h) and [`s`](#s) helpers.
+Single argument type for the [`h`](#h) and [`s`](#s) helpers.
 
 ### c
 
@@ -105,15 +107,30 @@ Argument type for the [`h`](#h) and [`s`](#s) helpers.
 const c: (root: CRoot, splitter?: string) => string;
 ```
 
-A minimal JS-to-CSS (CSS‑in‑JS) helper.
+A minimal CSS-in-JS helper that converts a JavaScript object hierarchy into a CSS string.
+
+#### root
+
+An object describing CSS rules.
+Keys are selectors or at-rules; values are either CSS property values or nested rule objects.
+
+#### 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`).
 
-The `root` object describes a hierarchy of CSS rules.
+#### Returns
 
-- Keys whose values are not objects are treated as CSS property names; their values become property values. The concatenation of parent keys produces a selector.
-- For every key, the substring from the splitter (default: `$$`) to the end is ignored (e.g. `src$$1` → `src`, `@font-face$$1` → `@font-face`).
-- In property keys, uppercase letters are converted to lowercase and prefixed with `-` (e.g. `fontFamily` → `font-family`); underscores are converted to `-` (e.g. `font_family` → `font-family`).
-- Commas inside selector keys cause them to expand into multiple selectors (e.g. `{div:{margin:1,'.a,.b,.c':{margin:2}}}` → `div{margin:1}div.a,div.b,div.c{margin:2}`).
-- Top-level keys beginning with `@` (at-rules) are not concatenated with parent keys.
+A CSS string representing the compiled rules.
+
+#### Remarks
+
+- Keys whose values are primitives (`string` | `number`) are treated as CSS properties.
+- In property keys, uppercase letters become lowercase with a `-` prefix (e.g., `fontFamily` → `font-family`);
+  underscores become hyphens (e.g., `font_family` → `font-family`).
+- Comma-separated selector keys expand into multiple selectors
+  (e.g., `{ div: { '.a,.b': { margin: 1 } } }` → `div.a,div.b{margin:1}`).
+- Top-level keys starting with `@` (at-rules) are not concatenated with child selectors.
 
 #### Usage Examples
 
@@ -317,7 +334,21 @@ expect(actual).to.deep.equal(expected)
 const csv_parse: (csv: string, separator?: string) => string[][];
 ```
 
-A tiny CSV parsing helper.
+Parses a CSV string into a two-dimensional array of strings.
+
+Supports quoted fields with escaped double quotes (`""`). Carriage returns are normalized.
+
+#### csv
+
+The CSV string to parse.
+
+#### separator
+
+The field delimiter (default: `','`).
+
+#### Returns
+
+A 2D array where each inner array represents a row of fields.
 
 #### Usage Examples
 
@@ -343,12 +374,29 @@ expect(csv_parse(text)).to.deep.equal([
 const escape: (escape_map: EscapeMap, template: TemplateStringsArray, ...values: unknown[]) => string;
 ```
 
-Escapes interpolated template `values` using the provided `escape_map`.
+Escapes interpolated values in a tagged template literal using the provided escape map.
+
+#### escape_map
+
+A map where keys are constructors and values are escape functions.
+
+#### template
+
+The template strings array from the tagged template.
+
+#### values
+
+The interpolated values to escape.
+
+#### Returns
+
+The resulting string with all interpolated values escaped.
 
 #### Usage Examples
 
 ```ts
 const escape_map: EscapeMap = new Map([
+  [null, () => 'NULL'],
   [undefined, () => 'NULL'],
   [Array, (values: unknown[]) => escape_values(escape_map, values).join(', ')],
   [Boolean, (value: boolean) => `b'${+value}'`],
@@ -378,7 +426,19 @@ expect(actual).to.deep.equal(expected)
 const escape_values: (escape_map: EscapeMap, values: unknown[]) => string[];
 ```
 
-Escapes array `values` using the provided `escape_map`.
+Escapes an array of values using the provided escape map.
+
+#### escape_map
+
+A map where keys are constructors (e.g., `String`, `Number`) and values are escape functions.
+
+#### values
+
+The array of values to escape.
+
+#### Returns
+
+An array of escaped strings.
 
 ### fix_typography
 
@@ -386,7 +446,16 @@ Escapes array `values` using the provided `escape_map`.
 const fix_typography: (node: Node) => void;
 ```
 
-Applies Polish‑specific typographic corrections.
+Applies Polish-specific typographic corrections to a DOM subtree.
+
+This function prevents orphaned conjunctions (single-letter words like “a”, “i”, “o”, “u”, “w”, “z”)
+from appearing at the end of a line by wrapping them with the following word in a non-breaking span.
+It also inserts zero-width spaces after slashes and dots to allow line breaks.
+
+#### node
+
+The root DOM node to process. All descendant text nodes are corrected recursively,
+except those inside `IFRAME`, `NOSCRIPT`, `PRE`, `SCRIPT`, `STYLE`, or `TEXTAREA` elements.
 
 #### Usage Examples
 
@@ -410,18 +479,28 @@ const h: {
 };
 ```
 
-A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper for creating and modifying `HTMLElement`s (see also [`s`](#s)).
+A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper
+for creating and modifying `HTMLElement`s (see also [`s`](#s)).
+
+#### tag_or_node
+
+If a `string`, it is treated as the tag name for a new element.
+If a `Node`, that node is modified in place.
 
-- If the first argument is a `string`, it is treated as the tag name to create.
-- If the first argument is a `Node`, that node is modified.
-- Object arguments map attributes/properties:
-  - Keys starting with `$` set element properties (without `$`).
-  - Other keys set attributes via `setAttribute`.
-  - Attributes with value `false` are removed via `removeAttribute`.
-- `null` / `undefined` are ignored.
-- `Node` arguments are appended.
-- `string` / `number` arguments become `Text` nodes.
-- [`HArgs`](#HArgs) arrays are processed recursively.
+#### args
+
+Additional arguments processed as follows:
+- `Object`: Maps attributes/properties. Keys starting with `$` set element properties
+  (without the `$` prefix); other keys set attributes via `setAttribute`.
+  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.
+
+#### Returns
+
+The created or modified `HTMLElement`.
 
 #### Usage Examples
 
@@ -502,7 +581,21 @@ expect(div.key).to.deep.equal({ one: 1, two: 2 })
 const has_own: (ref: unknown, key: unknown) => boolean;
 ```
 
-A replacement for the `in` operator (not to be confused with `for-in`).
+Checks whether an object has the specified key as its own property.
+
+A null-safe wrapper around `Object.hasOwn`.
+
+#### ref
+
+The object to check.
+
+#### key
+
+The property key to look for.
+
+#### Returns
+
+`true` if `ref` is not nullish and has `key` as an own property, `false` otherwise.
 
 #### Usage Examples
 
@@ -545,6 +638,14 @@ const is_array: (arg: unknown) => arg is unknown[];
 
 Checks whether the argument is an array.
 
+#### arg
+
+The value to check.
+
+#### Returns
+
+`true` if `arg` is an array, `false` otherwise.
+
 #### Usage Examples
 
 ```ts
@@ -557,7 +658,15 @@ expect(is_array([])).to.be.true
 const is_finite_number: (arg: unknown) => arg is number;
 ```
 
-Checks whether the argument is a finite number (excluding `±Infinity` and `NaN`).
+Checks whether the argument is a finite number (excludes `±Infinity` and `NaN`).
+
+#### arg
+
+The value to check.
+
+#### Returns
+
+`true` if `arg` is a finite number, `false` otherwise.
 
 #### Usage Examples
 
@@ -575,7 +684,15 @@ expect(is_finite_number(Infinity)).to.be.false
 const is_number: (arg: unknown) => arg is number;
 ```
 
-Checks whether the argument is a number.
+Checks whether the argument is of type `number` (includes `NaN` and `±Infinity`).
+
+#### arg
+
+The value to check.
+
+#### Returns
+
+`true` if `typeof arg === 'number'`, `false` otherwise.
 
 #### Usage Examples
 
@@ -593,7 +710,15 @@ expect(is_number(Infinity)).to.be.true
 const is_record: (arg: unknown) => arg is Record<PropertyKey, unknown>;
 ```
 
-Checks whether the argument is a plain object record.
+Checks whether the argument is a plain object (not `null` and not an array).
+
+#### arg
+
+The value to check.
+
+#### Returns
+
+`true` if `arg` is a plain object, `false` otherwise.
 
 #### Usage Examples
 
@@ -618,6 +743,14 @@ const is_string: (arg: unknown) => arg is string;
 
 Checks whether the argument is a string.
 
+#### arg
+
+The value to check.
+
+#### Returns
+
+`true` if `typeof arg === 'string'`, `false` otherwise.
+
 #### Usage Examples
 
 ```ts
@@ -632,29 +765,36 @@ expect(is_string(new String('42'))).to.be.false
 const js_on_parse: (handlers: Record<PropertyKey, Function>, text: string) => any;
 ```
 
-`JSON.parse` with “JavaScript turned on”.
+Parses JSON with support for handler-based value transformation (“JavaScript ON”).
 
-Objects having *exactly* one property whose name exists in `handlers`, i.e.:
+Objects with exactly one property whose key exists in `handlers` and whose value is an array
+are replaced by invoking the corresponding handler with the array elements as arguments.
 
-```js
-{ "«handler_name»": [«params»] }
-```
+#### handlers
 
-are replaced with:
+An object mapping handler names to functions.
 
-```js
-handlers['«handler_name»'](...«params»)
-```
+#### text
+
+The JSON string to parse.
+
+#### Returns
+
+The parsed value with handler substitutions applied.
 
 #### Usage Examples
 
 ```ts
 const handlers = {
+  $add: (a: number, b: number) => a + b,
   $hello: (name: string) => `Hello ${name}!`,
   $foo: () => 'bar'
 }
 
 const actual = js_on_parse(handlers, `[
+  {
+    "$add": [1, 2]
+  },
   {
     "$hello": ["World"]
   },
@@ -676,6 +816,7 @@ const actual = js_on_parse(handlers, `[
 ]`)
 
 const expected = [
+  3,
   'Hello World!',
   {
     nested: 'Hello nested World!',
@@ -693,33 +834,21 @@ const expected = [
 expect(actual).to.deep.equal(expected)
 ```
 
-### nanolight
+### nanolight_ts
 
 ```ts
-const nanolight: <M, T>(decorator: (chunk: string, metadata?: M) => T, ...rules: [M, string | RegExp][]) => (code: string) => T[];
+const nanolight_ts: (code: string) => HArgs1[];
 ```
 
-Generic syntax highlighting helper (see also [`nanolight_ts`](#nanolight_ts)).
+A TypeScript/JavaScript syntax highlighting tokenizer built using [`new_tokenizer`](#new_tokenizer).
 
-- `decorator` is a function that wraps each matched chunk.
-  It receives the matched text (`chunk`) and optionally the `metadata` associated with the pattern that produced the match.
-  For unmatched text between patterns, `metadata` is `undefined`.
-- `rules` is an array of tuples `[metadata, pattern]` where:
-  - `metadata`: data (e.g. CSS class name) passed to the `decorator` when the pattern matches.
-  - `pattern`: a `string` or `RegExp` to match against the code.
+#### code
 
-Matching rules:
-- For any two matches at different positions, the one starting earlier takes precedence.
-- For any two matches at the same position, the longer one takes precedence.
-- For any two matches at the same position and of the same length, the one defined earlier takes precedence.
+The source code string to tokenize.
 
-### nanolight_ts
-
-```ts
-const nanolight_ts: (code: string) => HArgs1[];
-```
+#### Returns
 
-TypeScript syntax highlighting helper (built on [`nanolight`](#nanolight)).
+An array of [`HArgs1`](#HArgs1) elements suitable for rendering with [`h`](#h) or [`s`](#s).
 
 #### Usage Examples
 
@@ -749,13 +878,57 @@ expect(nanolight_ts(code_js)).to.deep.equal([
 ])
 ```
 
+### new_tokenizer
+
+```ts
+const new_tokenizer: <M, T>(decorator: (chunk: string, metadata?: M) => T, ...specs: [M, string | RegExp][]) => (code: string) => T[];
+```
+
+A helper for building simple tokenizers (see also [`nanolight_ts`](#nanolight_ts)).
+
+#### decorator
+
+A function that wraps each matched chunk. It receives the matched text (`chunk`)
+and optionally the `metadata` associated with the pattern that produced the match.
+For unmatched text between patterns, `metadata` is `undefined`.
+
+#### specs
+
+An array of tuples `[metadata, pattern]` where:
+- `metadata`: Arbitrary data (e.g., a CSS class name) passed to `decorator` when the pattern matches.
+- `pattern`: A `string` or `RegExp` to match against the input.
+
+#### Returns
+
+A tokenizer function that accepts a code string and returns an array of decorated tokens.
+
+#### 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.
+
 ### omit
 
 ```ts
 const omit: <T, K extends keyof T>(ref: T, keys: unknown[]) => Omit<T, K>;
 ```
 
-Runtime implementation of TypeScript’s `Omit` (see also [`pick`](#pick)).
+Creates a new object excluding the specified keys from the source object.
+
+A runtime equivalent of TypeScript’s `Omit<T, K>` utility type. See also [`pick`](#pick).
+
+#### ref
+
+The source object.
+
+#### keys
+
+An array of keys to exclude from the result.
+
+#### Returns
+
+A new object without the specified keys.
 
 #### Usage Examples
 
@@ -771,7 +944,21 @@ expect(omit(obj, ['c'])).to.deep.equal({ a: 42, b: '42' })
 const pick: <T, K extends keyof T>(ref: T, keys: K[]) => Pick<T, K>;
 ```
 
-Runtime implementation of TypeScript’s `Pick` (see also [`omit`](#omit)).
+Creates a new object containing only the specified keys from the source object.
+
+A runtime equivalent of TypeScript’s `Pick<T, K>` utility type. See also [`omit`](#omit).
+
+#### ref
+
+The source object.
+
+#### keys
+
+An array of keys to include in the result.
+
+#### Returns
+
+A new object with only the specified keys.
 
 #### Usage Examples
 
@@ -787,7 +974,32 @@ expect(pick(obj, ['a', 'b'])).to.deep.equal({ a: 42, b: '42' })
 const pl_ural: (singular: string, plural_2: string, plural_5: string, value: number) => string;
 ```
 
-Chooses the appropriate Polish noun form based on a numeric value.
+Returns the appropriate Polish noun form based on a numeric value.
+
+Polish has three plural forms depending on the number:
+- Singular: used for exactly 1.
+- “Plural 2-4”: used for 2, 3, 4, 22, 23, 24, etc. (but not 12, 13, 14).
+- “Plural 5+”: used for 0, 5–21, 25–31, etc.
+
+#### singular
+
+The singular form (e.g., ”auto” for “car”).
+
+#### plural_2
+
+The form for 2, 3, 4 (e.g., “auta”).
+
+#### plural_5
+
+The form for 5+ (e.g., “aut”).
+
+#### value
+
+The numeric value to evaluate.
+
+#### Returns
+
+The appropriate noun form for the given value.
 
 #### Usage Examples
 
@@ -813,7 +1025,18 @@ expect(car(42)).to.deep.equal('cars')
 const pro: (ref: unknown) => any;
 ```
 
-A `Proxy`-based helper that safely creates nested structures on access and allows deep assignment without guards.
+A Proxy-based helper for auto-vivification of nested object structures.
+
+Accessing any property on the returned proxy automatically creates an empty object if the property does not exist,
+allowing deep assignments without explicit null checks.
+
+#### ref
+
+The root object to wrap.
+
+#### Returns
+
+A proxy that auto-creates nested objects on property access.
 
 #### Usage Examples
 
@@ -851,14 +1074,30 @@ expect(ref).to.deep.equal({ one: { two: { three: { four: 1234 } } } })
 const rwd: (root: CRoot, selector: string, cell_width_px: number, cell_height_px: number, ...specs: [number, number?, number?][]) => void;
 ```
 
-A responsive‑web‑design helper that generates CSS rules for a grid-like layout.
+A responsive web design helper that generates CSS rules for a grid-like layout.
+
+#### root
+
+The CSS root object to populate (see [`c`](#c)).
+
+#### selector
+
+The CSS selector for the grid item.
+
+#### cell_width_px
+
+The base cell width in pixels.
+
+#### cell_height_px
+
+The base cell height in pixels.
 
-- `root` and `selector` specify where to apply the generated rules (see [`c`](#c)).
-- `cell_width_px` and `cell_height_px` specify the base cell dimensions in pixels.
-- Each entry in `specs` is a tuple of:
-  - `max_width`: maximum number of cells in a row (viewport width breakpoint).
-  - `width` (optional, default: `1`): number of cells occupied by the element.
-  - `height` (optional, default: `1`): number of cells the element occupies vertically.
+#### specs
+
+An array of breakpoint specifications, each a tuple of:
+- `max_width`: Maximum number of cells per row (defines the viewport breakpoint).
+- `width` (optional, default `1`): Number of horizontal cells the element spans.
+- `height` (optional, default `1`): Number of vertical cells the element spans.
 
 #### Usage Examples
 
@@ -917,18 +1156,28 @@ const s: {
 };
 ```
 
-A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper for creating and modifying `SVGElement`s (see also [`h`](#h)).
+A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style helper
+for creating and modifying `SVGElement`s (see also [`h`](#h)).
+
+#### tag_or_node
+
+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); other keys set attributes via `setAttributeNS`.
+  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.
 
-- If the first argument is a `string`, it is treated as the tag name to create.
-- If the first argument is a `Node`, that node is modified.
-- Object arguments map attributes/properties:
-  - Keys starting with `$` set element properties (without `$`).
-  - Other keys set attributes via `setAttributeNS`.
-  - Attributes with value `false` are removed via `removeAttributeNS`.
-- `null` / `undefined` are ignored.
-- `Node` arguments are appended.
-- `string` / `number` arguments become `Text` nodes.
-- [`HArgs`](#HArgs) arrays are processed recursively.
+#### Returns
+
+The created or modified `SVGElement`.
 
 ### svg_use
 
@@ -936,7 +1185,21 @@ A lightweight [HyperScript](https://github.com/hyperhype/hyperscript)-style help
 const svg_use: (id: string, ...args: HArgs1[]) => SVGSVGElement;
 ```
 
-Shorthand for: `s('svg', ['use', { 'xlink:href': '#' + id }], ...args)`.
+Shorthand for creating an SVG element with a `<use>` child referencing an icon by ID.
+
+Equivalent to: `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.
 
 ### uuid_v1
 
@@ -946,7 +1209,18 @@ const uuid_v1: (date?: Date, node?: string) => string;
 
 Generates a UUID v1 (time-based) identifier.
 
-- Optional `node` must match `/^[0-9a-f]*$/`; it is trimmed to the last 12 characters and left-padded with zeros.
+#### date
+
+The date to use for the timestamp portion (default: current date/time).
+
+#### node
+
+A hexadecimal `string` for the node portion (default: random).
+Must match `/^[0-9a-f]*$/`; it is trimmed to the last 12 characters and left-padded with zeros if shorter.
+
+#### Returns
+
+A UUID v1 `string` in the standard format `xxxxxxxx-xxxx-1xxx-xxxx-xxxxxxxxxxxx`.
 
 #### Usage Examples