Add JSDoc type annotations to project (rebased)

5 files changed, 458 insertions, 165 deletions

diff --git a/ext/js/templates/sandbox/anki-template-renderer-content-manager.js b/ext/js/templates/sandbox/anki-template-renderer-content-manager.js
index 596fa499..be80c211 100644
--- a/ext/js/templates/sandbox/anki-template-renderer-content-manager.js
+++ b/ext/js/templates/sandbox/anki-template-renderer-content-manager.js
@@ -17,30 +17,21 @@
  */
 
 /**
- * A callback used when a media file has been loaded.
- * @callback AnkiTemplateRendererContentManager.OnLoadCallback
- * @param {string} url The URL of the media that was loaded.
- */
-
-/**
- * A callback used when a media file should be unloaded.
- * @callback AnkiTemplateRendererContentManager.OnUnloadCallback
- * @param {boolean} fullyLoaded Whether or not the media was fully loaded.
- */
-
-/**
  * The content manager which is used when generating content for Anki.
  */
 export class AnkiTemplateRendererContentManager {
     /**
      * Creates a new instance of the class.
      * @param {TemplateRendererMediaProvider} mediaProvider The media provider for the object.
-     * @param {object} data The data object passed to the Handlebars template renderer.
+     * @param {import('anki-templates').NoteData} data The data object passed to the Handlebars template renderer.
      *   See {@link AnkiNoteDataCreator.create}'s return value for structure information.
      */
     constructor(mediaProvider, data) {
+        /** @type {TemplateRendererMediaProvider} */
         this._mediaProvider = mediaProvider;
+        /** @type {import('anki-templates').NoteData} */
         this._data = data;
+        /** @type {import('anki-template-renderer-content-manager').OnUnloadCallback[]} */
         this._onUnloadCallbacks = [];
     }
 
@@ -48,9 +39,9 @@ export class AnkiTemplateRendererContentManager {
      * Attempts to load the media file from a given dictionary.
      * @param {string} path The path to the media file in the dictionary.
      * @param {string} dictionary The name of the dictionary.
-     * @param {AnkiTemplateRendererContentManager.OnLoadCallback} onLoad The callback that is executed if the media was loaded successfully.
+     * @param {import('anki-template-renderer-content-manager').OnLoadCallback} onLoad The callback that is executed if the media was loaded successfully.
      *   No assumptions should be made about the synchronicity of this callback.
-     * @param {AnkiTemplateRendererContentManager.OnUnloadCallback} onUnload The callback that is executed when the media should be unloaded.
+     * @param {import('anki-template-renderer-content-manager').OnUnloadCallback} onUnload The callback that is executed when the media should be unloaded.
      */
     loadMedia(path, dictionary, onLoad, onUnload) {
         const imageUrl = this._mediaProvider.getMedia(this._data, ['dictionaryMedia', path], {dictionary, format: 'fileName', default: null});
@@ -73,7 +64,7 @@ export class AnkiTemplateRendererContentManager {
 
     /**
      * Sets up attributes and events for a link element.
-     * @param {Element} element The link element.
+     * @param {HTMLAnchorElement} element The link element.
      * @param {string} href The URL.
      * @param {boolean} internal Whether or not the URL is an internal or external link.
      */
diff --git a/ext/js/templates/sandbox/anki-template-renderer.js b/ext/js/templates/sandbox/anki-template-renderer.js
index 10f69745..ce8e3200 100644
--- a/ext/js/templates/sandbox/anki-template-renderer.js
+++ b/ext/js/templates/sandbox/anki-template-renderer.js
@@ -36,17 +36,29 @@ export class AnkiTemplateRenderer {
      * Creates a new instance of the class.
      */
     constructor() {
+        /** @type {CssStyleApplier} */
         this._structuredContentStyleApplier = new CssStyleApplier('/data/structured-content-style.json');
+        /** @type {CssStyleApplier} */
         this._pronunciationStyleApplier = new CssStyleApplier('/data/pronunciation-style.json');
+        /** @type {RegExp} */
         this._structuredContentDatasetKeyIgnorePattern = /^sc([^a-z]|$)/;
+        /** @type {JapaneseUtil} */
         this._japaneseUtil = new JapaneseUtil(null);
+        /** @type {TemplateRenderer} */
         this._templateRenderer = new TemplateRenderer();
+        /** @type {AnkiNoteDataCreator} */
         this._ankiNoteDataCreator = new AnkiNoteDataCreator(this._japaneseUtil);
+        /** @type {TemplateRendererMediaProvider} */
         this._mediaProvider = new TemplateRendererMediaProvider();
+        /** @type {PronunciationGenerator} */
         this._pronunciationGenerator = new PronunciationGenerator(this._japaneseUtil);
+        /** @type {?(Map<string, unknown>[])} */
         this._stateStack = null;
+        /** @type {?import('anki-note-builder').Requirement[]} */
         this._requirements = null;
-        this._cleanupCallbacks = null;
+        /** @type {(() => void)[]} */
+        this._cleanupCallbacks = [];
+        /** @type {?HTMLElement} */
         this._temporaryElement = null;
     }
 
@@ -93,7 +105,7 @@ export class AnkiTemplateRenderer {
         ]);
         this._templateRenderer.registerDataType('ankiNote', {
             modifier: ({marker, commonData}) => this._ankiNoteDataCreator.create(marker, commonData),
-            composeData: (marker, commonData) => ({marker, commonData})
+            composeData: ({marker}, commonData) => ({marker, commonData})
         });
         this._templateRenderer.setRenderCallbacks(
             this._onRenderSetup.bind(this),
@@ -107,40 +119,56 @@ export class AnkiTemplateRenderer {
 
     // Private
 
+    /**
+     * @returns {{requirements: import('anki-note-builder').Requirement[]}}
+     */
     _onRenderSetup() {
+        /** @type {import('anki-note-builder').Requirement[]} */
         const requirements = [];
         this._stateStack = [new Map()];
         this._requirements = requirements;
         this._mediaProvider.requirements = requirements;
-        this._cleanupCallbacks = [];
         return {requirements};
     }
 
+    /**
+     * @returns {void}
+     */
     _onRenderCleanup() {
         for (const callback of this._cleanupCallbacks) { callback(); }
         this._stateStack = null;
         this._requirements = null;
         this._mediaProvider.requirements = null;
-        this._cleanupCallbacks = null;
+        this._cleanupCallbacks.length = 0;
     }
 
+    /**
+     * @param {string} text
+     * @returns {string}
+     */
     _escape(text) {
         return Handlebars.Utils.escapeExpression(text);
     }
 
+    /**
+     *
+     * @param text
+     */
     _safeString(text) {
         return new Handlebars.SafeString(text);
     }
 
     // Template helpers
 
-    _dumpObject(context, object) {
+    /** @type {import('template-renderer').HelperFunction<string>} */
+    _dumpObject(object) {
         const dump = JSON.stringify(object, null, 4);
         return this._escape(dump);
     }
 
-    _furigana(context, ...args) {
-        const {expression, reading} = this._getFuriganaExpressionAndReading(context, ...args);
+    /** @type {import('template-renderer').HelperFunction<string>} */
+    _furigana(args, context, options) {
+        const {expression, reading} = this._getFuriganaExpressionAndReading(args, context, options);
         const segs = this._japaneseUtil.distributeFurigana(expression, reading);
 
         let result = '';
@@ -157,8 +185,9 @@ export class AnkiTemplateRenderer {
         return this._safeString(result);
     }
 
-    _furiganaPlain(context, ...args) {
-        const {expression, reading} = this._getFuriganaExpressionAndReading(context, ...args);
+    /** @type {import('template-renderer').HelperFunction<string>} */
+    _furiganaPlain(args, context, options) {
+        const {expression, reading} = this._getFuriganaExpressionAndReading(args, context, options);
         const segs = this._japaneseUtil.distributeFurigana(expression, reading);
 
         let result = '';
@@ -174,43 +203,56 @@ export class AnkiTemplateRenderer {
         return result;
     }
 
-    _getFuriganaExpressionAndReading(context, ...args) {
-        if (args.length >= 3) {
-            return {expression: args[0], reading: args[1]};
-        } else if (args.length === 2) {
-            const {expression, reading} = args[0];
-            return {expression, reading};
+    /**
+     * @type {import('template-renderer').HelperFunction<{expression: string, reading: string}>}
+     */
+    _getFuriganaExpressionAndReading(args) {
+        let expression;
+        let reading;
+        if (args.length >= 2) {
+            [expression, reading] = /** @type {[expression?: string, reading?: string]} */ (args);
         } else {
-            return void 0;
+            ({expression, reading} = /** @type {import('core').SerializableObject} */ (args[0]));
         }
+        return {
+            expression: typeof expression === 'string' ? expression : '',
+            reading: typeof reading === 'string' ? reading : ''
+        };
     }
 
+    /**
+     *
+     * @param string
+     */
     _stringToMultiLineHtml(string) {
         return string.split('\n').join('<br>');
     }
 
-    _multiLine(context, options) {
-        return this._stringToMultiLineHtml(options.fn(context));
+    /** @type {import('template-renderer').HelperFunction<string>} */
+    _multiLine(_args, context, options) {
+        return this._stringToMultiLineHtml(this._asString(options.fn(context)));
     }
 
-    _regexReplace(context, ...args) {
+    /** @type {import('template-renderer').HelperFunction<string>} */
+    _regexReplace(args, context, options) {
         // Usage:
         // {{#regexReplace regex string [flags] [content]...}}content{{/regexReplace}}
         // regex: regular expression string
         // string: string to replace
         // flags: optional flags for regular expression
         //   e.g. "i" for case-insensitive, "g" for replace all
-        const argCount = args.length - 1;
-        const options = args[argCount];
-        let value = typeof options.fn === 'function' ? options.fn(context) : '';
+        const argCount = args.length;
+        let value = this._asString(options.fn(context));
         if (argCount > 3) {
             value = `${args.slice(3, -1).join('')}${value}`;
         }
         if (argCount > 1) {
             try {
-                const flags = argCount > 2 ? args[2] : 'g';
-                const regex = new RegExp(args[0], flags);
-                value = value.replace(regex, args[1]);
+                const [pattern, replacement, flags] = args;
+                if (typeof pattern !== 'string') { throw new Error('Invalid pattern'); }
+                if (typeof replacement !== 'string') { throw new Error('Invalid replacement'); }
+                const regex = new RegExp(pattern, typeof flags === 'string' ? flags : 'g');
+                value = value.replace(regex, replacement);
             } catch (e) {
                 return `${e}`;
             }
@@ -218,24 +260,26 @@ export class AnkiTemplateRenderer {
         return value;
     }
 
-    _regexMatch(context, ...args) {
+    /** @type {import('template-renderer').HelperFunction<string>} */
+    _regexMatch(args, context, options) {
         // Usage:
         // {{#regexMatch regex [flags] [content]...}}content{{/regexMatch}}
         // regex: regular expression string
         // flags: optional flags for regular expression
         //   e.g. "i" for case-insensitive, "g" for match all
-        const argCount = args.length - 1;
-        const options = args[argCount];
-        let value = typeof options.fn === 'function' ? options.fn(context) : '';
+        const argCount = args.length;
+        let value = this._asString(options.fn(context));
         if (argCount > 2) {
             value = `${args.slice(2, -1).join('')}${value}`;
         }
         if (argCount > 0) {
             try {
-                const flags = argCount > 1 ? args[1] : '';
-                const regex = new RegExp(args[0], flags);
+                const [pattern, flags] = args;
+                if (typeof pattern !== 'string') { throw new Error('Invalid pattern'); }
+                const regex = new RegExp(pattern, typeof flags === 'string' ? flags : '');
+                /** @type {string[]} */
                 const parts = [];
-                value.replace(regex, (g0) => parts.push(g0));
+                value.replace(regex, (g0) => { parts.push(g0); return g0; });
                 value = parts.join('');
             } catch (e) {
                 return `${e}`;
@@ -244,11 +288,18 @@ export class AnkiTemplateRenderer {
         return value;
     }
 
-    _mergeTags(context, object, isGroupMode, isMergeMode) {
+    /**
+     * @type {import('template-renderer').HelperFunction<string>}
+     */
+    _mergeTags(args) {
+        const [object, isGroupMode, isMergeMode] = /** @type {[object: import('anki-templates').TermDictionaryEntry, isGroupMode: boolean, isMergeMode: boolean]} */ (args);
         const tagSources = [];
         if (isGroupMode || isMergeMode) {
-            for (const definition of object.definitions) {
-                tagSources.push(definition.definitionTags);
+            const {definitions} = object;
+            if (Array.isArray(definitions)) {
+                for (const definition of definitions) {
+                    tagSources.push(definition.definitionTags);
+                }
             }
         } else {
             tagSources.push(object.definitionTags);
@@ -265,7 +316,9 @@ export class AnkiTemplateRenderer {
         return [...tags].join(', ');
     }
 
-    _eachUpTo(context, iterable, maxCount, options) {
+    /** @type {import('template-renderer').HelperFunction<string>} */
+    _eachUpTo(args, context, options) {
+        const [iterable, maxCount] = /** @type {[iterable: Iterable<unknown>, maxCount: number]} */ (args);
         if (iterable) {
             const results = [];
             let any = false;
@@ -279,14 +332,15 @@ export class AnkiTemplateRenderer {
                 return results.join('');
             }
         }
-        return options.inverse(context);
+        return this._asString(options.inverse(context));
     }
 
-    _spread(context, ...args) {
+    /** @type {import('template-renderer').HelperFunction<unknown[]>} */
+    _spread(args) {
         const result = [];
-        for (let i = 0, ii = args.length - 1; i < ii; ++i) {
+        for (const array of /** @type {Iterable<unknown>[]} */ (args)) {
             try {
-                result.push(...args[i]);
+                result.push(...array);
             } catch (e) {
                 // NOP
             }
@@ -294,15 +348,22 @@ export class AnkiTemplateRenderer {
         return result;
     }
 
-    _op(context, ...args) {
+    /** @type {import('template-renderer').HelperFunction<unknown>} */
+    _op(args) {
+        const [operator] = /** @type {[operator: string, operand1: import('core').SafeAny, operand2?: import('core').SafeAny, operand3?: import('core').SafeAny]} */ (args);
         switch (args.length) {
-            case 3: return this._evaluateUnaryExpression(args[0], args[1]);
-            case 4: return this._evaluateBinaryExpression(args[0], args[1], args[2]);
-            case 5: return this._evaluateTernaryExpression(args[0], args[1], args[2], args[3]);
+            case 2: return this._evaluateUnaryExpression(operator, args[1]);
+            case 3: return this._evaluateBinaryExpression(operator, args[1], args[2]);
+            case 4: return this._evaluateTernaryExpression(operator, args[1], args[2], args[3]);
             default: return void 0;
         }
     }
 
+    /**
+     * @param {string} operator
+     * @param {import('core').SafeAny} operand1
+     * @returns {unknown}
+     */
     _evaluateUnaryExpression(operator, operand1) {
         switch (operator) {
             case '+': return +operand1;
@@ -313,6 +374,12 @@ export class AnkiTemplateRenderer {
         }
     }
 
+    /**
+     * @param {string} operator
+     * @param {import('core').SafeAny} operand1
+     * @param {import('core').SafeAny} operand2
+     * @returns {unknown}
+     */
     _evaluateBinaryExpression(operator, operand1, operand2) {
         switch (operator) {
             case '+': return operand1 + operand2;
@@ -341,6 +408,13 @@ export class AnkiTemplateRenderer {
         }
     }
 
+    /**
+     * @param {string} operator
+     * @param {import('core').SafeAny} operand1
+     * @param {import('core').SafeAny} operand2
+     * @param {import('core').SafeAny} operand3
+     * @returns {unknown}
+     */
     _evaluateTernaryExpression(operator, operand1, operand2, operand3) {
         switch (operator) {
             case '?:': return operand1 ? operand2 : operand3;
@@ -348,8 +422,11 @@ export class AnkiTemplateRenderer {
         }
     }
 
-    _get(context, key) {
+    /** @type {import('template-renderer').HelperFunction<unknown>} */
+    _get(args) {
+        const [key] = /** @type {[key: string]} */ (args);
         const stateStack = this._stateStack;
+        if (stateStack === null) { throw new Error('Invalid state'); }
         for (let i = stateStack.length; --i >= 0;) {
             const map = stateStack[i];
             if (map.has(key)) {
@@ -359,19 +436,21 @@ export class AnkiTemplateRenderer {
         return void 0;
     }
 
-    _set(context, ...args) {
+    /** @type {import('template-renderer').HelperFunction<string>} */
+    _set(args, context, options) {
         const stateStack = this._stateStack;
+        if (stateStack === null) { throw new Error('Invalid state'); }
         switch (args.length) {
-            case 2:
+            case 1:
                 {
-                    const [key, options] = args;
+                    const [key] = /** @type {[key: string]} */ (args);
                     const value = options.fn(context);
                     stateStack[stateStack.length - 1].set(key, value);
                 }
                 break;
-            case 3:
+            case 2:
                 {
-                    const [key, value] = args;
+                    const [key, value] = /** @type {[key: string, value: unknown]} */ (args);
                     stateStack[stateStack.length - 1].set(key, value);
                 }
                 break;
@@ -379,8 +458,10 @@ export class AnkiTemplateRenderer {
         return '';
     }
 
-    _scope(context, options) {
+    /** @type {import('template-renderer').HelperFunction<unknown>} */
+    _scope(_args, context, options) {
         const stateStack = this._stateStack;
+        if (stateStack === null) { throw new Error('Invalid state'); }
         try {
             stateStack.push(new Map());
             return options.fn(context);
@@ -391,14 +472,25 @@ export class AnkiTemplateRenderer {
         }
     }
 
-    _property(context, ...args) {
-        const ii = args.length - 1;
+    /** @type {import('template-renderer').HelperFunction<unknown>} */
+    _property(args) {
+        const ii = args.length;
         if (ii <= 0) { return void 0; }
 
         try {
             let value = args[0];
             for (let i = 1; i < ii; ++i) {
-                value = value[args[i]];
+                if (typeof value !== 'object' || value === null) { throw new Error('Invalid object'); }
+                const key = args[i];
+                switch (typeof key) {
+                    case 'number':
+                    case 'string':
+                    case 'symbol':
+                        break;
+                    default:
+                        throw new Error('Invalid key');
+                }
+                value = /** @type {import('core').UnknownObject} */ (value)[key];
             }
             return value;
         } catch (e) {
@@ -406,38 +498,51 @@ export class AnkiTemplateRenderer {
         }
     }
 
-    _noop(context, options) {
+    /** @type {import('template-renderer').HelperFunction<unknown>} */
+    _noop(_args, context, options) {
         return options.fn(context);
     }
 
-    _isMoraPitchHigh(context, index, position) {
+    /** @type {import('template-renderer').HelperFunction<boolean>} */
+    _isMoraPitchHigh(args) {
+        const [index, position] = /** @type {[index: number, position: number]} */ (args);
         return this._japaneseUtil.isMoraPitchHigh(index, position);
     }
 
-    _getKanaMorae(context, text) {
+    /** @type {import('template-renderer').HelperFunction<string[]>} */
+    _getKanaMorae(args) {
+        const [text] = /** @type {[text: string]} */ (args);
         return this._japaneseUtil.getKanaMorae(`${text}`);
     }
 
-    _getTypeof(context, ...args) {
-        const ii = args.length - 1;
-        const value = (ii > 0 ? args[0] : args[ii].fn(context));
+    /** @type {import('template-renderer').HelperFunction<import('core').TypeofResult>} */
+    _getTypeof(args, context, options) {
+        const ii = args.length;
+        const value = (ii > 0 ? args[0] : options.fn(context));
         return typeof value;
     }
 
-    _join(context, ...args) {
-        return args.length > 1 ? args.slice(1, args.length - 1).flat().join(args[0]) : '';
+    /** @type {import('template-renderer').HelperFunction<string>} */
+    _join(args) {
+        return args.length > 0 ? args.slice(1, args.length).flat().join(/** @type {string} */ (args[0])) : '';
     }
 
-    _concat(context, ...args) {
+    /** @type {import('template-renderer').HelperFunction<string>} */
+    _concat(args) {
         let result = '';
-        for (let i = 0, ii = args.length - 1; i < ii; ++i) {
+        for (let i = 0, ii = args.length; i < ii; ++i) {
             result += args[i];
         }
         return result;
     }
 
-    _pitchCategories(context, data) {
-        const {pronunciations, headwords} = data.dictionaryEntry;
+    /** @type {import('template-renderer').HelperFunction<string[]>} */
+    _pitchCategories(args) {
+        const [data] = /** @type {[data: import('anki-templates').NoteData]} */ (args);
+        const {dictionaryEntry} = data;
+        if (dictionaryEntry.type !== 'term') { return []; }
+        const {pronunciations, headwords} = dictionaryEntry;
+        /** @type {Set<string>} */
         const categories = new Set();
         for (const {headwordIndex, pitches} of pronunciations) {
             const {reading, wordClasses} = headwords[headwordIndex];
@@ -452,6 +557,9 @@ export class AnkiTemplateRenderer {
         return [...categories];
     }
 
+    /**
+     * @returns {HTMLElement}
+     */
     _getTemporaryElement() {
         let element = this._temporaryElement;
         if (element === null) {
@@ -461,14 +569,28 @@ export class AnkiTemplateRenderer {
         return element;
     }
 
+    /**
+     * @param {Element} node
+     * @returns {string}
+     */
     _getStructuredContentHtml(node) {
         return this._getHtml(node, this._structuredContentStyleApplier, this._structuredContentDatasetKeyIgnorePattern);
     }
 
+    /**
+     * @param {Element} node
+     * @returns {string}
+     */
     _getPronunciationHtml(node) {
         return this._getHtml(node, this._pronunciationStyleApplier, null);
     }
 
+    /**
+     * @param {Element} node
+     * @param {CssStyleApplier} styleApplier
+     * @param {?RegExp} datasetKeyIgnorePattern
+     * @returns {string}
+     */
     _getHtml(node, styleApplier, datasetKeyIgnorePattern) {
         const container = this._getTemporaryElement();
         container.appendChild(node);
@@ -478,20 +600,27 @@ export class AnkiTemplateRenderer {
         return this._safeString(result);
     }
 
+    /**
+     * @param {Element} root
+     * @param {CssStyleApplier} styleApplier
+     * @param {?RegExp} datasetKeyIgnorePattern
+     */
     _normalizeHtml(root, styleApplier, datasetKeyIgnorePattern) {
         const {ELEMENT_NODE, TEXT_NODE} = Node;
         const treeWalker = document.createTreeWalker(root, NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT);
+        /** @type {HTMLElement[]} */
         const elements = [];
+        /** @type {Text[]} */
         const textNodes = [];
         while (true) {
             const node = treeWalker.nextNode();
             if (node === null) { break; }
             switch (node.nodeType) {
                 case ELEMENT_NODE:
-                    elements.push(node);
+                    elements.push(/** @type {HTMLElement} */ (node));
                     break;
                 case TEXT_NODE:
-                    textNodes.push(node);
+                    textNodes.push(/** @type {Text} */ (node));
                     break;
             }
         }
@@ -508,8 +637,11 @@ export class AnkiTemplateRenderer {
         }
     }
 
+    /**
+     * @param {Text} textNode
+     */
     _replaceNewlines(textNode) {
-        const parts = textNode.nodeValue.split('\n');
+        const parts = /** @type {string} */ (textNode.nodeValue).split('\n');
         if (parts.length <= 1) { return; }
         const {parentNode} = textNode;
         if (parentNode === null) { return; }
@@ -521,6 +653,10 @@ export class AnkiTemplateRenderer {
         parentNode.replaceChild(fragment, textNode);
     }
 
+    /**
+     * @param {import('anki-templates').NoteData} data
+     * @returns {StructuredContentGenerator}
+     */
     _createStructuredContentGenerator(data) {
         const contentManager = new AnkiTemplateRendererContentManager(this._mediaProvider, data);
         const instance = new StructuredContentGenerator(contentManager, this._japaneseUtil, document);
@@ -528,44 +664,65 @@ export class AnkiTemplateRenderer {
         return instance;
     }
 
-    _formatGlossary(context, dictionary, content, options) {
+    /**
+     * @type {import('template-renderer').HelperFunction<string>}
+     */
+    _formatGlossary(args, context, options) {
+        const [dictionary] = /** @type {[dictionary: string]} */ (args);
         const data = options.data.root;
+        const content = /** @type {import('dictionary-data').TermGlossary} */ (args[0]);
         if (typeof content === 'string') { return this._stringToMultiLineHtml(this._escape(content)); }
         if (!(typeof content === 'object' && content !== null)) { return ''; }
         switch (content.type) {
             case 'image': return this._formatGlossaryImage(content, dictionary, data);
             case 'structured-content': return this._formatStructuredContent(content, dictionary, data);
+            case 'text': return this._stringToMultiLineHtml(this._escape(content.text));
         }
         return '';
     }
 
+    /**
+     * @param {import('dictionary-data').TermGlossaryImage} content
+     * @param {string} dictionary
+     * @param {import('anki-templates').NoteData} data
+     * @returns {string}
+     */
     _formatGlossaryImage(content, dictionary, data) {
         const structuredContentGenerator = this._createStructuredContentGenerator(data);
         const node = structuredContentGenerator.createDefinitionImage(content, dictionary);
         return this._getStructuredContentHtml(node);
     }
 
+    /**
+     * @param {import('dictionary-data').TermGlossaryStructuredContent} content
+     * @param {string} dictionary
+     * @param {import('anki-templates').NoteData} data
+     * @returns {string}
+     */
     _formatStructuredContent(content, dictionary, data) {
         const structuredContentGenerator = this._createStructuredContentGenerator(data);
         const node = structuredContentGenerator.createStructuredContent(content.content, dictionary);
         return node !== null ? this._getStructuredContentHtml(node) : '';
     }
 
-    _hasMedia(context, ...args) {
-        const ii = args.length - 1;
-        const options = args[ii];
-        return this._mediaProvider.hasMedia(options.data.root, args.slice(0, ii), options.hash);
+    /**
+     * @type {import('template-renderer').HelperFunction<boolean>}
+     */
+    _hasMedia(args, _context, options) {
+        return this._mediaProvider.hasMedia(options.data.root, args, options.hash);
     }
 
-    _getMedia(context, ...args) {
-        const ii = args.length - 1;
-        const options = args[ii];
-        return this._mediaProvider.getMedia(options.data.root, args.slice(0, ii), options.hash);
+    /**
+     * @type {import('template-renderer').HelperFunction<?string>}
+     */
+    _getMedia(args, _context, options) {
+        return this._mediaProvider.getMedia(options.data.root, args, options.hash);
     }
 
-    _pronunciation(context, ...args) {
-        const ii = args.length - 1;
-        const options = args[ii];
+    /**
+     * @type {import('template-renderer').HelperFunction<string>}
+     */
+    _pronunciation(_args, _context, options) {
         let {format, reading, downstepPosition, nasalPositions, devoicePositions} = options.hash;
 
         if (typeof reading !== 'string' || reading.length === 0) { return ''; }
@@ -586,18 +743,30 @@ export class AnkiTemplateRenderer {
         }
     }
 
-    _hiragana(context, ...args) {
-        const ii = args.length - 1;
-        const options = args[ii];
+    /**
+     * @type {import('template-renderer').HelperFunction<string>}
+     */
+    _hiragana(args, context, options) {
+        const ii = args.length;
         const {keepProlongedSoundMarks} = options.hash;
         const value = (ii > 0 ? args[0] : options.fn(context));
-        return this._japaneseUtil.convertKatakanaToHiragana(value, keepProlongedSoundMarks === true);
+        return typeof value === 'string' ? this._japaneseUtil.convertKatakanaToHiragana(value, keepProlongedSoundMarks === true) : '';
     }
 
-    _katakana(context, ...args) {
-        const ii = args.length - 1;
-        const options = args[ii];
+    /**
+     * @type {import('template-renderer').HelperFunction<string>}
+     */
+    _katakana(args, context, options) {
+        const ii = args.length;
         const value = (ii > 0 ? args[0] : options.fn(context));
-        return this._japaneseUtil.convertHiraganaToKatakana(value);
+        return typeof value === 'string' ? this._japaneseUtil.convertHiraganaToKatakana(value) : '';
+    }
+
+    /**
+     * @param {unknown} value
+     * @returns {string}
+     */
+    _asString(value) {
+        return typeof value === 'string' ? value : `${value}`;
     }
 }
diff --git a/ext/js/templates/sandbox/template-renderer-frame-api.js b/ext/js/templates/sandbox/template-renderer-frame-api.js
index 7ce2d909..31ba4500 100644
--- a/ext/js/templates/sandbox/template-renderer-frame-api.js
+++ b/ext/js/templates/sandbox/template-renderer-frame-api.js
@@ -17,15 +17,23 @@
  */
 
 export class TemplateRendererFrameApi {
+    /**
+     * @param {TemplateRenderer} templateRenderer
+     */
     constructor(templateRenderer) {
+        /** @type {TemplateRenderer} */
         this._templateRenderer = templateRenderer;
-        this._windowMessageHandlers = new Map([
+        /** @type {import('core').MessageHandlerMap} */
+        this._windowMessageHandlers = new Map(/** @type {import('core').MessageHandlerArray} */ ([
             ['render', {async: false, handler: this._onRender.bind(this)}],
             ['renderMulti', {async: false, handler: this._onRenderMulti.bind(this)}],
             ['getModifiedData', {async: false, handler: this._onGetModifiedData.bind(this)}]
-        ]);
+        ]));
     }
 
+    /**
+     * @returns {void}
+     */
     prepare() {
         window.addEventListener('message', this._onWindowMessage.bind(this), false);
         this._postMessage(window.parent, 'ready', {}, null);
@@ -33,14 +41,24 @@ export class TemplateRendererFrameApi {
 
     // Private
 
+    /**
+     * @param {MessageEvent<import('template-renderer-frame-api').MessageData>} e
+     */
     _onWindowMessage(e) {
         const {source, data: {action, params, id}} = e;
         const messageHandler = this._windowMessageHandlers.get(action);
         if (typeof messageHandler === 'undefined') { return; }
 
-        this._onWindowMessageInner(messageHandler, action, params, source, id);
+        this._onWindowMessageInner(messageHandler, action, params, /** @type {Window} */ (source), id);
     }
 
+    /**
+     * @param {import('core').MessageHandlerDetails} handlerItem
+     * @param {string} action
+     * @param {import('core').SerializableObject} params
+     * @param {Window} source
+     * @param {?string} id
+     */
     async _onWindowMessageInner({handler, async}, action, params, source, id) {
         let response;
         try {
@@ -50,64 +68,54 @@ export class TemplateRendererFrameApi {
             }
             response = {result};
         } catch (error) {
-            response = {error: this._serializeError(error)};
+            response = {error: ExtensionError.serialize(error)};
         }
 
         if (typeof id === 'undefined') { return; }
         this._postMessage(source, `${action}.response`, response, id);
     }
 
+    /**
+     * @param {{template: string, data: import('template-renderer').PartialOrCompositeRenderData, type: import('anki-templates').RenderMode}} event
+     * @returns {import('template-renderer').RenderResult}
+     */
     _onRender({template, data, type}) {
         return this._templateRenderer.render(template, data, type);
     }
 
+    /**
+     * @param {{items: import('template-renderer').RenderMultiItem[]}} event
+     * @returns {import('core').Response<import('template-renderer').RenderResult>[]}
+     */
     _onRenderMulti({items}) {
-        return this._serializeMulti(this._templateRenderer.renderMulti(items));
+        return this._templateRenderer.renderMulti(items);
     }
 
+    /**
+     * @param {{data: import('template-renderer').CompositeRenderData, type: import('anki-templates').RenderMode}} event
+     * @returns {import('anki-templates').NoteData}
+     */
     _onGetModifiedData({data, type}) {
         const result = this._templateRenderer.getModifiedData(data, type);
         return this._clone(result);
     }
 
-    _serializeError(error) {
-        try {
-            if (typeof error === 'object' && error !== null) {
-                const result = {
-                    name: error.name,
-                    message: error.message,
-                    stack: error.stack
-                };
-                if (Object.prototype.hasOwnProperty.call(error, 'data')) {
-                    result.data = error.data;
-                }
-                return result;
-            }
-        } catch (e) {
-            // NOP
-        }
-        return {
-            value: error,
-            hasValue: true
-        };
-    }
-
-    _serializeMulti(array) {
-        for (let i = 0, ii = array.length; i < ii; ++i) {
-            const value = array[i];
-            const {error} = value;
-            if (typeof error !== 'undefined') {
-                value.error = this._serializeError(error);
-            }
-        }
-        return array;
-    }
-
+    /**
+     * @template [T=unknown]
+     * @param {T} value
+     * @returns {T}
+     */
     _clone(value) {
         return JSON.parse(JSON.stringify(value));
     }
 
+    /**
+     * @param {Window} target
+     * @param {string} action
+     * @param {import('core').SerializableObject} params
+     * @param {?string} id
+     */
     _postMessage(target, action, params, id) {
-        return target.postMessage({action, params, id}, '*');
+        target.postMessage(/** @type {import('template-renderer-frame-api').MessageData} */ ({action, params, id}), '*');
     }
 }
diff --git a/ext/js/templates/sandbox/template-renderer-media-provider.js b/ext/js/templates/sandbox/template-renderer-media-provider.js
index 33ddec21..d8a0a16d 100644
--- a/ext/js/templates/sandbox/template-renderer-media-provider.js
+++ b/ext/js/templates/sandbox/template-renderer-media-provider.js
@@ -20,9 +20,11 @@ import {Handlebars} from '../../../lib/handlebars.js';
 
 export class TemplateRendererMediaProvider {
     constructor() {
+        /** @type {?import('anki-note-builder').Requirement[]} */
         this._requirements = null;
     }
 
+    /** @type {?import('anki-note-builder').Requirement[]} */
     get requirements() {
         return this._requirements;
     }
@@ -31,12 +33,24 @@ export class TemplateRendererMediaProvider {
         this._requirements = value;
     }
 
+    /**
+     * @param {import('anki-templates').NoteData} root
+     * @param {unknown[]} args
+     * @param {import('core').SerializableObject} namedArgs
+     * @returns {boolean}
+     */
     hasMedia(root, args, namedArgs) {
         const {media} = root;
         const data = this._getMediaData(media, args, namedArgs);
         return (data !== null);
     }
 
+    /**
+     * @param {import('anki-templates').NoteData} root
+     * @param {unknown[]} args
+     * @param {import('core').SerializableObject} namedArgs
+     * @returns {?string}
+     */
     getMedia(root, args, namedArgs) {
         const {media} = root;
         const data = this._getMediaData(media, args, namedArgs);
@@ -45,16 +59,24 @@ export class TemplateRendererMediaProvider {
             if (typeof result === 'string') { return result; }
         }
         const defaultValue = namedArgs.default;
-        return typeof defaultValue !== 'undefined' ? defaultValue : '';
+        return defaultValue === null || typeof defaultValue === 'string' ? defaultValue : '';
     }
 
     // Private
 
+    /**
+     * @param {import('anki-note-builder').Requirement} value
+     */
     _addRequirement(value) {
         if (this._requirements === null) { return; }
         this._requirements.push(value);
     }
 
+    /**
+     * @param {import('anki-templates').MediaObject} data
+     * @param {import('core').SerializableObject} namedArgs
+     * @returns {string}
+     */
     _getFormattedValue(data, namedArgs) {
         let {value} = data;
         const {escape=true} = namedArgs;
@@ -64,6 +86,12 @@ export class TemplateRendererMediaProvider {
         return value;
     }
 
+    /**
+     * @param {import('anki-templates').Media} media
+     * @param {unknown[]} args
+     * @param {import('core').SerializableObject} namedArgs
+     * @returns {?(import('anki-templates').MediaObject)}
+     */
     _getMediaData(media, args, namedArgs) {
         const type = args[0];
         switch (type) {
@@ -78,6 +106,11 @@ export class TemplateRendererMediaProvider {
         }
     }
 
+    /**
+     * @param {import('anki-templates').Media} media
+     * @param {import('anki-templates').MediaSimpleType} type
+     * @returns {?import('anki-templates').MediaObject}
+     */
     _getSimpleMediaData(media, type) {
         const result = media[type];
         if (typeof result === 'object' && result !== null) { return result; }
@@ -85,12 +118,19 @@ export class TemplateRendererMediaProvider {
         return null;
     }
 
+    /**
+     * @param {import('anki-templates').Media} media
+     * @param {unknown} path
+     * @param {import('core').SerializableObject} namedArgs
+     * @returns {?import('anki-templates').MediaObject}
+     */
     _getDictionaryMedia(media, path, namedArgs) {
+        if (typeof path !== 'string') { return null; }
         const {dictionaryMedia} = media;
         const {dictionary} = namedArgs;
+        if (typeof dictionary !== 'string') { return null; }
         if (
             typeof dictionaryMedia !== 'undefined' &&
-            typeof dictionary === 'string' &&
             Object.prototype.hasOwnProperty.call(dictionaryMedia, dictionary)
         ) {
             const dictionaryMedia2 = dictionaryMedia[dictionary];
@@ -109,8 +149,15 @@ export class TemplateRendererMediaProvider {
         return null;
     }
 
+    /**
+     * @param {import('anki-templates').Media} media
+     * @param {unknown} text
+     * @param {import('core').SerializableObject} namedArgs
+     * @returns {?import('anki-templates').MediaObject}
+     */
     _getTextFurigana(media, text, namedArgs) {
-        const {readingMode=null} = namedArgs;
+        if (typeof text !== 'string') { return null; }
+        const readingMode = this._normalizeReadingMode(namedArgs.readingMode);
         const {textFurigana} = media;
         if (Array.isArray(textFurigana)) {
             for (const entry of textFurigana) {
@@ -125,4 +172,18 @@ export class TemplateRendererMediaProvider {
         });
         return null;
     }
+
+    /**
+     * @param {unknown} value
+     * @returns {?import('anki-templates').TextFuriganaReadingMode}
+     */
+    _normalizeReadingMode(value) {
+        switch (value) {
+            case 'hiragana':
+            case 'katakana':
+                return value;
+            default:
+                return null;
+        }
+    }
 }
diff --git a/ext/js/templates/sandbox/template-renderer.js b/ext/js/templates/sandbox/template-renderer.js
index 8d8a2765..c7613533 100644
--- a/ext/js/templates/sandbox/template-renderer.js
+++ b/ext/js/templates/sandbox/template-renderer.js
@@ -20,47 +20,74 @@ import {Handlebars} from '../../../lib/handlebars.js';
 
 export class TemplateRenderer {
     constructor() {
+        /** @type {Map<string, HandlebarsTemplateDelegate<import('anki-templates').NoteData>>} */
         this._cache = new Map();
+        /** @type {number} */
         this._cacheMaxSize = 5;
+        /** @type {Map<import('anki-templates').RenderMode, import('template-renderer').DataType>} */
         this._dataTypes = new Map();
+        /** @type {?((noteData: import('anki-templates').NoteData) => import('template-renderer').SetupCallbackResult)} */
         this._renderSetup = null;
+        /** @type {?((noteData: import('anki-templates').NoteData) => import('template-renderer').CleanupCallbackResult)} */
         this._renderCleanup = null;
     }
 
+    /**
+     * @param {import('template-renderer').HelperFunctionsDescriptor} helpers
+     */
     registerHelpers(helpers) {
         for (const [name, helper] of helpers) {
             this._registerHelper(name, helper);
         }
     }
 
-    registerDataType(name, {modifier=null, composeData=null}) {
+    /**
+     * @param {import('anki-templates').RenderMode} name
+     * @param {import('template-renderer').DataType} details
+     */
+    registerDataType(name, {modifier, composeData}) {
         this._dataTypes.set(name, {modifier, composeData});
     }
 
+    /**
+     * @param {?((noteData: import('anki-templates').NoteData) => import('template-renderer').SetupCallbackResult)} setup
+     * @param {?((noteData: import('anki-templates').NoteData) => import('template-renderer').CleanupCallbackResult)} cleanup
+     */
     setRenderCallbacks(setup, cleanup) {
         this._renderSetup = setup;
         this._renderCleanup = cleanup;
     }
 
+    /**
+     * @param {string} template
+     * @param {import('template-renderer').PartialOrCompositeRenderData} data
+     * @param {import('anki-templates').RenderMode} type
+     * @returns {import('template-renderer').RenderResult}
+     */
     render(template, data, type) {
         const instance = this._getTemplateInstance(template);
-        data = this._getModifiedData(data, void 0, type);
-        return this._renderTemplate(instance, data);
+        const modifiedData = this._getModifiedData(data, void 0, type);
+        return this._renderTemplate(instance, modifiedData);
     }
 
+    /**
+     * @param {import('template-renderer').RenderMultiItem[]} items
+     * @returns {import('core').Response<import('template-renderer').RenderResult>[]}
+     */
     renderMulti(items) {
+        /** @type {import('core').Response<import('template-renderer').RenderResult>[]} */
         const results = [];
         for (const {template, templateItems} of items) {
             const instance = this._getTemplateInstance(template);
             for (const {type, commonData, datas} of templateItems) {
-                for (let data of datas) {
+                for (const data of datas) {
                     let result;
                     try {
-                        data = this._getModifiedData(data, commonData, type);
-                        result = this._renderTemplate(instance, data);
-                        result = {result};
+                        const data2 = this._getModifiedData(data, commonData, type);
+                        const renderResult = this._renderTemplate(instance, data2);
+                        result = {result: renderResult};
                     } catch (error) {
-                        result = {error};
+                        result = {error: ExtensionError.serialize(error)};
                     }
                     results.push(result);
                 }
@@ -69,29 +96,46 @@ export class TemplateRenderer {
         return results;
     }
 
+    /**
+     * @param {import('template-renderer').CompositeRenderData} data
+     * @param {import('anki-templates').RenderMode} type
+     * @returns {import('anki-templates').NoteData}
+     */
     getModifiedData(data, type) {
         return this._getModifiedData(data, void 0, type);
     }
 
     // Private
 
+    /**
+     * @param {string} template
+     * @returns {HandlebarsTemplateDelegate<import('anki-templates').NoteData>}
+     */
     _getTemplateInstance(template) {
         const cache = this._cache;
         let instance = cache.get(template);
         if (typeof instance === 'undefined') {
             this._updateCacheSize(this._cacheMaxSize - 1);
-            instance = Handlebars.compileAST(template);
+            instance = /** @type {HandlebarsTemplateDelegate<import('anki-templates').NoteData>} */ (Handlebars.compileAST(template));
             cache.set(template, instance);
         }
 
         return instance;
     }
 
+    /**
+     * @param {HandlebarsTemplateDelegate<import('anki-templates').NoteData>} instance
+     * @param {import('anki-templates').NoteData} data
+     * @returns {import('template-renderer').RenderResult}
+     */
     _renderTemplate(instance, data) {
         const renderSetup = this._renderSetup;
         const renderCleanup = this._renderCleanup;
+        /** @type {string} */
         let result;
+        /** @type {?import('template-renderer').SetupCallbackResult} */
         let additions1;
+        /** @type {?import('template-renderer').CleanupCallbackResult} */
         let additions2;
         try {
             additions1 = (typeof renderSetup === 'function' ? renderSetup(data) : null);
@@ -99,28 +143,36 @@ export class TemplateRenderer {
         } finally {
             additions2 = (typeof renderCleanup === 'function' ? renderCleanup(data) : null);
         }
-        return Object.assign({result}, additions1, additions2);
+        return /** @type {import('template-renderer').RenderResult} */ (Object.assign({result}, additions1, additions2));
     }
 
+    /**
+     * @param {import('template-renderer').PartialOrCompositeRenderData} data
+     * @param {import('anki-note-builder').CommonData|undefined} commonData
+     * @param {import('anki-templates').RenderMode} type
+     * @returns {import('anki-templates').NoteData}
+     * @throws {Error}
+     */
     _getModifiedData(data, commonData, type) {
         if (typeof type === 'string') {
             const typeInfo = this._dataTypes.get(type);
             if (typeof typeInfo !== 'undefined') {
                 if (typeof commonData !== 'undefined') {
                     const {composeData} = typeInfo;
-                    if (typeof composeData === 'function') {
-                        data = composeData(data, commonData);
-                    }
+                    data = composeData(data, commonData);
+                } else if (typeof data.commonData === 'undefined') {
+                    throw new Error('Incomplete data');
                 }
                 const {modifier} = typeInfo;
-                if (typeof modifier === 'function') {
-                    data = modifier(data);
-                }
+                return modifier(/** @type {import('template-renderer').CompositeRenderData} */ (data));
             }
         }
-        return data;
+        throw new Error(`Invalid type: ${type}`);
     }
 
+    /**
+     * @param {number} maxSize
+     */
     _updateCacheSize(maxSize) {
         const cache = this._cache;
         let removeCount = cache.size - maxSize;
@@ -132,9 +184,21 @@ export class TemplateRenderer {
         }
     }
 
+    /**
+     * @param {string} name
+     * @param {import('template-renderer').HelperFunction} helper
+     */
     _registerHelper(name, helper) {
+        /**
+         * @this {unknown}
+         * @param {unknown[]} args
+         * @returns {unknown}
+         */
         function wrapper(...args) {
-            return helper(this, ...args);
+            const argCountM1 = Math.max(0, args.length - 1);
+            const options = /** @type {Handlebars.HelperOptions} */ (args[argCountM1]);
+            args.length = argCountM1;
+            return helper(args, this, options);
         }
         Handlebars.registerHelper(name, wrapper);
     }