estreui 1.2.3 → 1.2.4

package/scripts/doctre.js

@@ -30,7 +30,7 @@ SOFTWARE.
 // 
 // Cold(array object) assigning of HTML Tree for make to JSON string.
 // 
-// v1.1.1 / release 2026.02.20
+// v1.1.2 / release 2026.04.18
 // 
 // cold = [] - Cold HTML child node list
 // cold[0] - Tag name, classes, id, name, type = "tag.class1.class2#id@name$type" : string
@@ -45,8 +45,63 @@ SOFTWARE.
 // Match replace
 // ex) Doctre.parse([["|tag|.|classes|#|id|", "empty content"], "|divider|"], { tag: () => isInline ? "span" | "div", classes: "test fixed", id: getId(), divider: it => '<hr class="' + it + '" />' })
 
+// ──────────────────────────────────────────────
+// @typedef — reusable type shapes
+// ──────────────────────────────────────────────
+
+/**
+ * Extracted solidId components.
+ * @typedef {Object} DoctreSolidId
+ * @property {string} tagName - HTML tag name.
+ * @property {string} [class] - Space-separated CSS class names.
+ * @property {string} [id] - Element id.
+ * @property {string} [name] - Element name attribute.
+ * @property {string} [type] - Element type attribute.
+ */
+
+/**
+ * A single cold element entry — serialized DOM node in array form.
+ *
+ * `[solidId, contentData, style, attrs, datas]`
+ * @typedef {Array} DoctreColdElement
+ * @property {string|DoctreSolidId} 0 - solidId string or extracted object.
+ * @property {DoctreColdElement[]|string|null} [1] - Child content (cold array, text, or null).
+ * @property {string|Object} [2] - Inline style string or style object.
+ * @property {Object<string, string>} [3] - Regular HTML attributes (excluding id/name/type/class/style/data-*).
+ * @property {Object<string, string>} [4] - data-* attributes.
+ */
+
+/**
+ * Token replacement map used by Doctre.matchReplace.
+ * Keys are token names (matched as `|key|`); values are replacement strings, functions, or objects.
+ * @typedef {Object<string, string|Function|Object>} DoctreMatchReplacer
+ * @property {string} [dataPlaceholder] - Default replacement for unmatched tokens.
+ * @property {boolean} [coverReplaceable] - If true, replaces all unmatched tokens with dataPlaceholder.
+ */
+
+/**
+ * Document Object Cold Taste Refrigeration Effortlessness — DOM serialization/deserialization engine.
+ * Preserves and restores HTML trees using cold (array object) and frost (JSON string) formats.
+ *
+ * **cold format**: `[solidId, contentData, style, attrs, datas]`
+ * - `solidId`: `"tag.class1.class2#id@name$type"` string or extracted object
+ * - `contentData`: cold array / text string / NodeList / Element / Node
+ * - `style`: style string or object
+ * - `attrs`: regular attribute object
+ * - `datas`: data-* attribute object
+ *
+ * **frost format**: JSON.stringify'd cold string
+ *
+ * **matchReplace**: replaces `|key|` tokens with values from the matchReplacer object
+ * @class
+ */
 class Doctre {
 
+    /**
+     * Splits a solidId string into the tag name and remaining major attribute parts.
+     * @param {string|Object} solidId - solidId string or `{ tagName, ... }` object.
+     * @returns {[string, string|Object]} `[tagName, majorAttrs]` tuple.
+     */
     static extractTagName(solidId) {
         let tagName, majorAttrs;
         if (typeof solidId == "string") {
@@ -61,6 +116,12 @@ class Doctre {
         return [tagName, majorAttrs];
     }
 
+    /**
+     * Parses the major attribute part (`.class#id@name$type`) of a solidId into an object.
+     * @param {string} majorAttrs - Major attribute string.
+     * @param {Object} [to={}] - Object to store results into.
+     * @returns {Object} `{ class?, id?, name?, type? }` attribute object.
+     */
     static extractMajorAttrs(majorAttrs, to = {}) {
         const process = (string, divider, attrName) => {
             const filter = new RegExp(divider + "[\\w.-]*");
@@ -77,12 +138,28 @@ class Doctre {
         return to;
     }
 
+    /**
+     * Extracts both the tag name and major attributes from a solidId.
+     * @param {string} solidId - solidId string.
+     * @returns {Object} `{ tagName, class?, id?, name?, type? }`.
+     */
     static extractTagAndMajorAttrs(solidId) {
         const [tagName, majorAttrs] = this.extractTagName(solidId);
         return this.extractMajorAttrs(majorAttrs, { tagName });
     }
 
 
+    /**
+     * Creates a DOM element from cold parameters.
+     * @param {string|Array} [tagName="template"] - Tag name or cold array.
+     * @param {string|Object} [majorAttrs] - Major attributes string/object.
+     * @param {string|Array|NodeList|Node|Doctre|null} [contentData] - Child content.
+     * @param {string|Object} [style={}] - Style.
+     * @param {Object} [attrs={}] - Regular attributes.
+     * @param {Object} [datas={}] - data-* attributes.
+     * @param {DoctreMatchReplacer} [matchReplacer={}] - `|key|` token replacement map.
+     * @returns {Element} The created DOM element.
+     */
     static createElement(tagName = "template", majorAttrs, contentData, style = {}, attrs = {}, datas = {}, matchReplacer = {}) {
         if (tagName instanceof Array) return this.createElement(...tagName);
 
@@ -132,10 +209,32 @@ class Doctre {
         return element;
     }
 
+    /**
+     * createElement variant that takes matchReplacer as the first argument.
+     * @param {DoctreMatchReplacer} matchReplacer - Token replacement map.
+     * @param {string} tagName - Tag name.
+     * @param {string|Object} [majorAttrs] - Major attributes.
+     * @param {*} [contentData] - Child content.
+     * @param {string|Object} [style={}] - Style.
+     * @param {Object} [attrs={}] - Regular attributes.
+     * @param {Object} [datas={}] - data-* attributes.
+     * @param {DoctreMatchReplacer} [matchReplacerOrigin={}] - Fallback when matchReplacer is null.
+     * @returns {Element}
+     */
     static createElementReplaced(matchReplacer, tagName, majorAttrs, contentData, style = {}, attrs = {}, datas = {}, matchReplacerOrigin = {}) {
         return this.createElement(tagName, majorAttrs, contentData, style, attrs, datas, matchReplacer ?? matchReplacerOrigin);
     }
 
+    /**
+     * Creates an element from a solidId string. Automatically extracts tagName and majorAttrs from solidId.
+     * @param {string|Array} solidId - solidId string or array.
+     * @param {*} [contentData] - Child content.
+     * @param {string|Object} [style={}] - Style.
+     * @param {Object} [attrs={}] - Regular attributes.
+     * @param {Object} [datas={}] - data-* attributes.
+     * @param {DoctreMatchReplacer} [matchReplacer={}] - Token replacement map.
+     * @returns {Element}
+     */
     static createElementBy(solidId, contentData, style = {}, attrs = {}, datas = {}, matchReplacer = {}) {
         if (solidId instanceof Array) return this.createElementBy(...solidId);
 
@@ -143,10 +242,27 @@ class Doctre {
         return this.createElement(tagName, majorAttrs, contentData, style, attrs, datas, matchReplacer);
     }
 
+    /**
+     * createElementBy variant that takes matchReplacer as the first argument.
+     * @param {DoctreMatchReplacer} matchReplacer - Token replacement map.
+     * @param {string} solidId - solidId string.
+     * @param {*} [contentData] - Child content.
+     * @param {string|Object} [style={}] - Style.
+     * @param {Object} [attrs={}] - Regular attributes.
+     * @param {Object} [datas={}] - data-* attributes.
+     * @param {DoctreMatchReplacer} [matchReplacerOrigin={}] - Fallback replacement map.
+     * @returns {Element}
+     */
     static createElementReplacedBy(matchReplacer, solidId, contentData, style = {}, attrs = {}, datas = {}, matchReplacerOrigin = {}) {
         return this.createElementBy(solidId, contentData, style, attrs, datas, matchReplacer ?? matchReplacerOrigin);
     }
 
+    /**
+     * Creates a DocumentFragment from a cold (HCNL) array.
+     * @param {Array} hcnlArray - HTML Cold Node List array.
+     * @param {DoctreMatchReplacer} [matchReplacer={}] - Token replacement map.
+     * @returns {DocumentFragment}
+     */
     static createFragment(hcnlArray, matchReplacer = {}) {
         const df = document.createDocumentFragment();
         for (const val of hcnlArray) switch (typeof val) {
@@ -168,22 +284,42 @@ class Doctre {
         return df;
     }
 
+    /** @type {string} Current User-Agent string. */
     static get userAgent() { return navigator?.userAgent ?? ""; }
+    /** @type {boolean} Whether newline/tab escaping is needed for Safari/iOS. */
     static get isRequiredEscape() {
         const userAgent = this.userAgent;
         return userAgent != "" && (userAgent.includes("iPad") || userAgent.includes("iPhone") || userAgent.includes("iPod") || (userAgent.includes("Macintosh") && !userAgent.includes("Chrome") && !userAgent.includes("Firefox") && !userAgent.includes("Edge") && !userAgent.includes("Opera")));
     }
+    /**
+     * Escapes newlines and tabs in JSON strings for Safari compatibility.
+     * @param {string} jsonContent - JSON string.
+     * @returns {string} Escaped string (returned as-is on non-Safari).
+     */
     static crashBroker(jsonContent) {
         if (this.isRequiredEscape) jsonContent = jsonContent.replace(/\r\n/gm, "\\r\\n").replace(/\n\r/gm, "\\n\\r").replace(/\r/gm, "\\r").replace(/\n/gm, "\\n").replace(/\t/g, "\\t");
         return jsonContent;
     }
 
+    /**
+     * Copies only primitive-type values from an object. Used to avoid circular references.
+     * @param {Object} obj - Source object.
+     * @returns {Object} A new object containing only primitive values.
+     */
     static copyPrimitives(obj) {
         return Object.fromEntries(
             Object.entries(obj).filter(([, v]) => v !== Object(v))
         );
     }
 
+    /**
+     * Replaces `|key|` tokens in a string with values from the matchReplacer. Delegates to matchReplaceObject for objects.
+     * @param {string|Object} frostOrString - String or object to apply replacements to.
+     * @param {DoctreMatchReplacer} [matchReplacer={}] - `{ key: value }` replacement map. Values can be string/function/object.
+     *   - `dataPlaceholder`: default replacement for unmatched tokens.
+     *   - `coverReplaceable`: if true, replaces all unmatched tokens with dataPlaceholder.
+     * @returns {string|Object} The replaced result.
+     */
     static matchReplace(frostOrString, matchReplacer = {}) {
         if (typeof frostOrString != "string") return this.matchReplaceObject(frostOrString, matchReplacer);
 
@@ -249,12 +385,24 @@ class Doctre {
         return frostOrString;
     }
 
+    /**
+     * Recursively applies matchReplace to both keys and values of an object.
+     * @param {Object} object - Object to apply replacements to.
+     * @param {DoctreMatchReplacer} [matchReplacer={}] - Replacement map.
+     * @returns {Object} A new object with replacements applied.
+     */
     static matchReplaceObject(object, matchReplacer = {}) {
         const replaced = object.constructor();
         for (const key in object) replaced[this.matchReplace(key, matchReplacer)] = this.matchReplace(object[key], matchReplacer);
         return replaced;
     }
 
+    /**
+     * Parses a frost (JSON string) and restores it as a DocumentFragment.
+     * @param {string} frost - Frost format JSON string.
+     * @param {DoctreMatchReplacer} [matchReplacer={}] - Token replacement map.
+     * @returns {DocumentFragment}
+     */
     static parse(frost, matchReplacer = {}) {
         frost = this.crashBroker(frost);
         const trimmedFrost = frost.trim();
@@ -273,11 +421,23 @@ class Doctre {
         return this.createFragment(parsed);
     }
 
+    /**
+     * Restores frost (string) or cold (array) to a live DOM (DocumentFragment).
+     * @param {string|Array} frostOrCold - Frost string or cold array.
+     * @param {DoctreMatchReplacer} [matchReplacer={}] - Token replacement map.
+     * @returns {DocumentFragment}
+     */
     static live(frostOrCold, matchReplacer = {}) {
         if (typeof frostOrCold == "string") return this.parse(frostOrCold, matchReplacer);
         else return this.createFragment(frostOrCold);
     }
 
+    /**
+     * Wraps frost/cold in a template element and returns it.
+     * @param {string|Array} frostOrCold - Frost or cold data.
+     * @param {DoctreMatchReplacer} [matchReplacer={}] - Token replacement map.
+     * @returns {Element} Template element containing the content.
+     */
     static takeOut(frostOrCold, matchReplacer = {}) {
         const element = this.createElement();
         element.append(this.live(frostOrCold, matchReplacer));
@@ -285,6 +445,15 @@ class Doctre {
     }
 
 
+    /**
+     * Assembles a solidId string from tag name and major attributes.
+     * @param {string} tagName - Tag name.
+     * @param {string} [className] - CSS classes (space-separated).
+     * @param {string} [id] - ID.
+     * @param {string} [name] - name attribute.
+     * @param {string} [type] - type attribute.
+     * @returns {string} solidId string (e.g. `"div.box.float#app@root$text"`).
+     */
     static getSolidId(tagName, className, id, name, type) {
         let solidId = tagName;
         if (className != null) solidId += "." + className.replace(/ /g, ".");
@@ -294,6 +463,12 @@ class Doctre {
         return solidId;
     }
 
+    /**
+     * Extracts the tag name and major attributes (class, id, name, type) from a DOM element.
+     * @param {Element} element - Target element.
+     * @param {boolean} [asSolidId=false] - If true returns solidId string, if false returns object.
+     * @returns {string|Object} solidId string or `{ tagName, class?, id?, name?, type? }`.
+     */
     static packTagAndMajorAttrs(element, asSolidId = false) {
         const tagName = element.tagName.toLowerCase();
         const className = element.getAttribute("class");
@@ -312,6 +487,11 @@ class Doctre {
         }
     }
 
+    /**
+     * Parses a CSS style string into a `{ property: value }` object.
+     * @param {string} style - Inline style string.
+     * @returns {Object<string, string>}
+     */
     static getStyleObject(style) {
         const styles = {};
         const divided = style.split(";");
@@ -325,6 +505,11 @@ class Doctre {
         return styles;
     }
 
+    /**
+     * Extracts attributes from a NamedNodeMap, excluding id/name/type/class/style/data-*.
+     * @param {NamedNodeMap} attrs - Element's attributes.
+     * @returns {Object<string, string>}
+     */
     static packAttributes(attrs) {
         const pack = {};
         for (const attr of attrs) {
@@ -345,6 +530,11 @@ class Doctre {
         return pack;
     }
 
+    /**
+     * Copies a DOMStringMap (dataset) to a plain object.
+     * @param {DOMStringMap} dataset - Element's dataset.
+     * @returns {Object<string, string>}
+     */
     static getDataObject(dataset) {
         const datas = {};
         for (const key in dataset) datas[key] = dataset[key];
@@ -352,6 +542,11 @@ class Doctre {
     }
 
 
+    /**
+     * Removes trailing empty entries (null, empty string, empty array, empty object) from an HECP (cold element array).
+     * @param {Array} hecp - Cold element array `[solidId, content, style, attrs, datas]`.
+     * @returns {Array} The trimmed array (mutates the original).
+     */
     static trimHecp(hecp) {
         for (var i = hecp.length - 1; i > 0; i--) {
             if (hecp[i] == null) delete hecp[i];
@@ -367,6 +562,16 @@ class Doctre {
         return hecp;
     }
 
+    /**
+     * Serializes a DOM element into a cold array.
+     * @param {Element} element - Target element.
+     * @param {boolean} [trimBobbleNode=false] - Remove whitespace-only text nodes.
+     * @param {boolean} [trimHecp=false] - Trim trailing empty entries.
+     * @param {boolean} [styleToObject=!trimHecp] - Convert style to object.
+     * @param {boolean} [trimIndent=trimHecp] - Trim text indentation.
+     * @param {boolean} [elementAsDoctre=!trimHecp] - Preserve child elements as Doctre instances.
+     * @returns {Array} Cold array.
+     */
     static frostElement(element, trimBobbleNode = false, trimHecp = false, styleToObject = !trimHecp, trimIndent = trimHecp, elementAsDoctre = !trimHecp) {
         const frozen = [];
         frozen.push(this.packTagAndMajorAttrs(element, !elementAsDoctre));
@@ -379,6 +584,12 @@ class Doctre {
         return trimHecp ? this.trimHecp(frozen) : frozen;
     }
 
+    /**
+     * Trims leading/trailing whitespace from each line of text.
+     * @param {string} text - Source text.
+     * @param {boolean} [trimIndent=false] - If true, fully removes indentation; if false, collapses to single space.
+     * @returns {string}
+     */
     static trimTextIndent(text, trimIndent = false) {
         return text.split("\n").map(line => {
             let std = line.trimStart();
@@ -389,6 +600,16 @@ class Doctre {
         }).join("\n");
     }
 
+    /**
+     * Serializes a single node to cold format. Branches by node type.
+     * @param {Node|Doctre|Array} node - Target node.
+     * @param {boolean} [trimBobbleNode=false] - Remove whitespace text nodes.
+     * @param {boolean} [trimHecp=false] - Trim trailing empty entries.
+     * @param {boolean} [styleToObject=!trimHecp] - Convert style to object.
+     * @param {boolean} [trimIndent=trimHecp] - Trim text indentation.
+     * @param {boolean} [elementAsDoctre=!trimHecp] - Preserve child elements as Doctre.
+     * @returns {Array|Doctre|string} Cold array, Doctre instance, or text string.
+     */
     static frostNode(node, trimBobbleNode = false, trimHecp = false, styleToObject = !trimHecp, trimIndent = trimHecp, elementAsDoctre = !trimHecp) {
         if (node instanceof Doctre) return elementAsDoctre ? node : node.frost(trimBobbleNode, trimHecp, styleToObject, trimIndent, elementAsDoctre);
         else if (node instanceof DocumentFragment) return this.coldify(node.childNodes, trimBobbleNode, trimHecp, styleToObject, trimIndent, elementAsDoctre);
@@ -400,6 +621,16 @@ class Doctre {
         }
     }
 
+    /**
+     * Serializes a node or node list into a cold array.
+     * @param {Node|NodeList|Doctre|string} nodeOrList - Target node/list.
+     * @param {boolean} [trimBobbleNode=false] - Remove whitespace text nodes.
+     * @param {boolean} [trimHecp=false] - Trim trailing empty entries.
+     * @param {boolean} [styleToObject=!trimHecp] - Convert style to object.
+     * @param {boolean} [trimIndent=trimHecp] - Trim text indentation.
+     * @param {boolean} [elementAsDoctre=!trimHecp] - Preserve child elements as Doctre.
+     * @returns {Array} Cold array.
+     */
     static coldify(nodeOrList, trimBobbleNode = false, trimHecp = false, styleToObject = !trimHecp, trimIndent = trimHecp, elementAsDoctre = !trimHecp) {
         if (typeof nodeOrList == "string") return this.coldify([nodeOrList], trimBobbleNode, trimHecp, styleToObject, trimIndent, elementAsDoctre);
 
@@ -413,6 +644,16 @@ class Doctre {
         return cold;
     }
 
+    /**
+     * Serializes node/list/cold to frost (JSON string).
+     * @param {Node|NodeList|Array} nodeOrListOrCold - Target.
+     * @param {boolean|number} [prettyJson=false] - If true or a number (indent), produces pretty-printed JSON.
+     * @param {boolean} [trimBobbleNode=false] - Remove whitespace text nodes.
+     * @param {boolean} [trimHecp=true] - Trim trailing empty entries.
+     * @param {boolean} [styleToObject=!trimHecp] - Convert style to object.
+     * @param {boolean} [trimIndent=trimHecp] - Trim text indentation.
+     * @returns {string} Frost JSON string.
+     */
     static stringify(nodeOrListOrCold, prettyJson = false, trimBobbleNode = false, trimHecp = true, styleToObject = !trimHecp, trimIndent = trimHecp) {
         const cold = this.coldify(nodeOrListOrCold, trimBobbleNode, trimHecp, styleToObject, trimIndent, false);
 
@@ -421,6 +662,17 @@ class Doctre {
     }
 
 
+    /**
+     * Injects Doctre convenience methods into Node, NodeList, Element, and jQuery prototypes.
+     *
+     * **NodeList/Node**: `coldify`, `coldified`, `stringify`, `stringified`
+     * **Element**: `cold`, `takeCold`, `frozen`, `takeFrozen`,
+     *   `alive`(append), `alone`(replace+append),
+     *   `freeze`(→data-frozen), `solid`(freeze+clear),
+     *   `hot`(data-frozen→fragment), `worm`(hot+append), `melt`(clear+worm),
+     *   `burn`(hot+delete data), `wormOut`(worm+delete), `meltOut`(clear+wormOut)
+     * **jQuery**: `coldify`, `coldified`, `stringify`, `stringified` (only when jQuery is available)
+     */
     static patch() {
         const attach = (cls, name, value) => Object.defineProperty(cls.prototype, name, { value, writable: true, configurable: true, enumerable: false });
         const attachGS = (cls, name, getter, setter) => Object.defineProperty(cls.prototype, name, { getter, setter, configurable: true, enumerable: false });
@@ -464,22 +716,35 @@ class Doctre {
     }
 
 
+    /** @type {string} Tag name. */
     tagName;
-
+    /** @type {string[]} CSS class array. */
     classes;
-
+    /** @type {string|undefined} ID. */
     id;
+    /** @type {string|undefined} name attribute. */
     name;
+    /** @type {string|undefined} type attribute. */
     type;
-
+    /** @type {Array} Child cold array (Doctre instances or strings). */
     childDoctres;
-
+    /** @type {string|Object} Style. */
     style;
+    /** @type {Object} Regular attributes. */
     attrs;
+    /** @type {Object} data-* attributes. */
     datas;
-
+    /** @type {DoctreMatchReplacer} Default token replacement map. */
     matchReplacer;
 
+    /**
+     * @param {string|Object|Array} [solidIdOrExtracted] - solidId string, extracted object, or cold array.
+     * @param {*} [contentData] - Child content.
+     * @param {string|Object} [style={}] - Style.
+     * @param {Object} [attrs={}] - Regular attributes.
+     * @param {Object} [datas={}] - data-* attributes.
+     * @param {DoctreMatchReplacer} [matchReplacer={}] - Token replacement map.
+     */
     constructor(solidIdOrExtracted, contentData, style = {}, attrs = {}, datas = {}, matchReplacer = {}) {
         if (solidIdOrExtracted instanceof Array) {
             solidIdOrExtracted = solidIdOrExtracted[0];
@@ -511,9 +776,11 @@ class Doctre {
         this.matchReplacer = matchReplacer ?? {};
     }
 
+    /** @type {string} Space-separated class string. */
     get className() { return this.classes.join(" "); }
     set className(value) { this.classes = value.split(" "); }
 
+    /** @type {Object} Major attributes object `{ class, id, name, type }`. */
     get majorAttrs() {
         return {
             class: this.className,
@@ -523,20 +790,46 @@ class Doctre {
         };
     }
 
+    /** @type {string} solidId string for this instance. */
     get solidId() { return Doctre.getSolidId(this.tagName, this.className, this.id, this.name, this.type); }
 
 
+    /** @type {Element} Creates a live DOM element from this Doctre (without default matchReplacer). */
     get live() { return Doctre.createElement(this.tagName, this.majorAttrs, this.childDoctres, this.style, this.attrs, this.datas); }
 
+    /**
+     * Creates a live DOM element with the applied matchReplacer.
+     * @param {DoctreMatchReplacer} [matchReplacer] - Token replacement map. Uses instance default if omitted.
+     * @returns {Element}
+     */
     fresh(matchReplacer) { return Doctre.createElement(this.tagName, this.majorAttrs, this.childDoctres, this.style, this.attrs, this.datas, matchReplacer ?? this.matchReplacer ?? {}); }
 
+    /**
+     * Serializes this Doctre to a cold array.
+     * @param {boolean} [trimBobbleNode=false]
+     * @param {boolean} [trimHecp=false]
+     * @param {boolean} [styleToObject=!trimHecp]
+     * @param {boolean} [trimIndent=trimHecp]
+     * @param {boolean} [elementAsDoctre=!trimHecp]
+     * @returns {Array} Cold array.
+     */
     frost(trimBobbleNode = false, trimHecp = false, styleToObject = !trimHecp, trimIndent = trimHecp, elementAsDoctre = !trimHecp) {
         const hecp = [[this.solidId, this.cold(trimBobbleNode, trimHecp, styleToObject, trimIndent, elementAsDoctre), this.style, this.attrs, this.datas]];
         return trimHecp ? Doctre.trimHecp(hecp) : hecp;
     }
 
+    /** @type {Array} Compact (trimmed) frost — `frost(false, true, false, false)`. */
     get icy() { return this.frost(false, true, false, false); }
 
+    /**
+     * Serializes this Doctre to a frost JSON string.
+     * @param {boolean|number} [prettyJson=false]
+     * @param {boolean} [trimBobbleNode=false]
+     * @param {boolean} [trimHecp=true]
+     * @param {boolean} [styleToObject=!trimHecp]
+     * @param {boolean} [trimIndent=trimHecp]
+     * @returns {string} Frost JSON string.
+     */
     toString(prettyJson = false, trimBobbleNode = false, trimHecp = true, styleToObject = !trimHecp, trimIndent = trimHecp) {
         const hecp = this.frost(trimBobbleNode, trimHecp, styleToObject, trimIndent, false);
         if (prettyJson == null || prettyJson === false) return JSON.stringify(hecp);
@@ -545,19 +838,50 @@ class Doctre {
 
 
 
+    /** @type {DocumentFragment} Restores child cold to a live DocumentFragment. */
     get chill() { return Doctre.createFragment(this.childDoctres); }
 
+    /**
+     * Serializes child content to a cold array.
+     * @param {boolean} [trimBobbleNode=false]
+     * @param {boolean} [trimHecp=false]
+     * @param {boolean} [styleToObject=!trimHecp]
+     * @param {boolean} [trimIndent=trimHecp]
+     * @param {boolean} [elementAsDoctre=!trimHecp]
+     * @returns {Array}
+     */
     cold(trimBobbleNode = false, trimHecp = false, styleToObject = !trimHecp, trimIndent = trimHecp, elementAsDoctre = !trimHecp) {
         return Doctre.coldify(this.childDoctres, trimBobbleNode, trimHecp, styleToObject, trimIndent, elementAsDoctre);
     }
 
+    /**
+     * Serializes child content to a frost JSON string.
+     * @param {boolean|number} [prettyJson=false]
+     * @param {boolean} [trimBobbleNode=false]
+     * @param {boolean} [trimHecp=true]
+     * @param {boolean} [styleToObject=!trimHecp]
+     * @param {boolean} [trimIndent=trimHecp]
+     * @returns {string}
+     */
     frozen(prettyJson = false, trimBobbleNode = false, trimHecp = true, styleToObject = !trimHecp, trimIndent = trimHecp) {
         return Doctre.stringify(this.childDoctres, prettyJson, trimBobbleNode, trimHecp, styleToObject, trimIndent);
     }
 }
 
+/**
+ * Node array extending Array. Preserves nodes from DocumentFragment or NodeList as an array.
+ * Since a Fragment loses its children when appended to the DOM, use NodeArray to maintain references.
+ * @class
+ * @extends Array
+ */
 class NodeArray extends Array {
 
+    /**
+     * Copies nodes from a DocumentFragment or NodeList into a NodeArray.
+     * @param {DocumentFragment|NodeList} fragmentOrNodeList - Source.
+     * @param {NodeArray} [into=new NodeArray()] - Array to store results into.
+     * @returns {NodeArray}
+     */
     static box(fragmentOrNodeList, into = new NodeArray()) {
         const nodeList = fragmentOrNodeList instanceof DocumentFragment ? fragmentOrNodeList.childNodes : fragmentOrNodeList;
         for (const node of nodeList) into.push(node);

package/scripts/estreU0EEOZ.js

@@ -12,7 +12,11 @@
 
 Doctre?.patch?.();
 
-// document aliases
+/**
+ * Document access shorthand object — DOM queries, element creation, Doctre integration.
+ * `doc.b` = document.body, `doc.ce()` = Doctre.createElement, `doc.l()` = Doctre.live, etc.
+ * @type {Object}
+ */
 const doc = {
     get b() { return document.body; },
     get $b() { return $(this.b); },
@@ -879,10 +883,20 @@ class EUX {
 
 
 /**
- * Estre Local styler
+ * Estre Local Styler — generates local-scope styles by replacing `##` tokens with the CSS path up to the parent element.
+ *
+ * When `##` is used in an HTML `<style>` tag, it is automatically replaced based on the style tag's position
+ * with a parent → ancestor CSS selector chain. Achieves scoped style effect without Shadow DOM.
+ * @class
  */
 class LocalStyle {
 
+    /**
+     * Replaces `##` in the element's style text with the local CSS selector path.
+     * @param {Element|null} elem - Element containing style text. If null, adds directly to location.
+     * @param {string} [styleText=elem.innerHTML] - Style text to replace.
+     * @param {Element} [location=elem.parentElement] - Base element for the local path.
+     */
     static localize(elem, styleText = elem.innerHTML, location = elem.parentElement) {
         const htmlEntities = {
             "&nbsp;": " ",
@@ -947,6 +961,11 @@ class LocalStyle {
         }
     }
 
+    /**
+     * Directly adds a local style at the given location.
+     * @param {Element} location - Base element to insert the style at.
+     * @param {string} localStyle - Style text containing `##`.
+     */
     static appendLocalize(location, localStyle) {
         this.localize(null, localStyle, location);
     }
@@ -954,7 +973,9 @@ class LocalStyle {
 
 
 /**
- * Locale constants
+ * Estre locale constants — per-language weekday names, month names, date/time prefix/suffix collections.
+ * Detects the current language via `EsLocale.currentLanguage` and looks up locale strings from `EsLocale.collections`.
+ * @class
  */
 class EsLocale {
     static get currentLocale() { return navigator.language; }
@@ -1574,7 +1595,7 @@ const Ecal = {
         }
     },
 
-    /** 시간순 정렬 함수 */
+    /** Chronological sort function */
     byTime: (a, b) => a.time - b.time,
 
     eoo