diff --git a/api/components/corner-action.mjs b/api/components/corner-action.mjs
index 2ebf808..bf42f9b 100644
--- a/api/components/corner-action.mjs
+++ b/api/components/corner-action.mjs
@@ -7,10 +7,7 @@
 
 'use strict';
 
-/**
- * shared notion-style elements
- * @module notion-enhancer/api/components/corner-action
- */
+/** shared notion-style elements */
 
 import { web } from '../index.mjs';
 
diff --git a/api/components/feather.mjs b/api/components/feather.mjs
index 6e2350f..9bd68fd 100644
--- a/api/components/feather.mjs
+++ b/api/components/feather.mjs
@@ -6,10 +6,7 @@
 
 'use strict';
 
-/**
- * shared notion-style elements
- * @module notion-enhancer/api/components/feather
- */
+/** shared notion-style elements */
 
 import { fs, web } from '../index.mjs';
 
diff --git a/api/components/index.mjs b/api/components/index.mjs
index ab690bd..28c52b5 100644
--- a/api/components/index.mjs
+++ b/api/components/index.mjs
@@ -8,19 +8,20 @@
 
 /**
  * shared notion-style elements
- * @module notion-enhancer/api/components
+ * @namespace components
  */
+import * as _api from '../index.mjs'; // trick jsdoc
 
 /**
  * add a tooltip to show extra information on hover
  * @param {HTMLElement} $ref - the element that will trigger the tooltip when hovered
  * @param {string|HTMLElement} $content - markdown or element content of the tooltip
- * @param {object=} [options] - configuration of how the tooltip should be displayed
- * @param {number} [options.delay] - the amount of time in ms the element needs to be hovered over
+ * @param {object=} options - configuration of how the tooltip should be displayed
+ * @param {number=} options.delay - the amount of time in ms the element needs to be hovered over
  * for the tooltip to be shown (default: 100)
- * @param {string} [options.offsetDirection] - which side of the element the tooltip
+ * @param {string=} options.offsetDirection - which side of the element the tooltip
  * should be shown on: 'top', 'bottom', 'left' or 'right' (default: 'bottom')
- * @param {number} [options.maxLines] - the max number of lines that the content may be wrapped
+ * @param {number=} options.maxLines - the max number of lines that the content may be wrapped
  * to, used to position and size the tooltip correctly (default: 1)
  */
 export { addTooltip } from './tooltip.mjs';
diff --git a/api/components/panel.mjs b/api/components/panel.mjs
index 73225d6..8f82a58 100644
--- a/api/components/panel.mjs
+++ b/api/components/panel.mjs
@@ -7,10 +7,7 @@
 
 'use strict';
 
-/**
- * shared notion-style elements
- * @module notion-enhancer/api/components/side-panel
- */
+/** shared notion-style elements */
 
 import { web, components, registry } from '../index.mjs';
 
@@ -63,7 +60,7 @@ const panelPinnedAttr = 'data-enhancer-panel-pinned',
     db.set(['panel.pinned'], isPinned());
   },
   // resize
-  updateWidth = async () => {
+  updateWidth = () => {
     document.documentElement.style.setProperty('--component--panel-width', panelWidth + 'px');
     db.set(['panel.width'], panelWidth);
   },
@@ -78,7 +75,7 @@ const panelPinnedAttr = 'data-enhancer-panel-pinned',
     $notionFrame.style.paddingRight = panelWidth + 'px';
     if ($notionRightSidebar) $notionRightSidebar.style.right = panelWidth + 'px';
   },
-  resizeEnd = (event) => {
+  resizeEnd = (_event) => {
     $panel.style.width = '';
     $hoverTrigger.style.width = '';
     $notionFrame.style.paddingRight = '';
@@ -151,16 +148,18 @@ const panelPinnedAttr = 'data-enhancer-panel-pinned',
           document.activeElement.click();
           event.stopPropagation();
           break;
-        case 'ArrowUp':
+        case 'ArrowUp': {
           const $prev = event.target.previousElementSibling;
           ($prev || event.target.parentElement.lastElementChild).focus();
           event.stopPropagation();
           break;
-        case 'ArrowDown':
+        }
+        case 'ArrowDown': {
           const $next = event.target.nextElementSibling;
           ($next || event.target.parentElement.firstElementChild).focus();
           event.stopPropagation();
           break;
+        }
       }
     }
   },
@@ -240,7 +239,7 @@ async function enablePanelResize() {
   });
 }
 
-async function createViews() {
+function createViews() {
   $notionApp = document.querySelector('.notion-app-inner');
   $header.addEventListener('click', openSwitcher);
   $switcherTrigger.addEventListener('click', openSwitcher);
diff --git a/api/components/tooltip.mjs b/api/components/tooltip.mjs
index f78cdc7..80f1d03 100644
--- a/api/components/tooltip.mjs
+++ b/api/components/tooltip.mjs
@@ -6,10 +6,7 @@
 
 'use strict';
 
-/**
- * shared notion-style elements
- * @module notion-enhancer/api/components/tooltip
- */
+/** shared notion-style elements */
 
 import { fs, web } from '../index.mjs';
 
@@ -20,7 +17,7 @@ const countLines = ($el) =>
       (prev, val) => (prev.some((p) => p.y === val.y) ? prev : [...prev, val]),
       []
     ).length,
-  position = async ($ref, offsetDirection, maxLines) => {
+  position = ($ref, offsetDirection, maxLines) => {
     _$tooltip.style.top = `0px`;
     _$tooltip.style.left = `0px`;
     const rect = $ref.getBoundingClientRect(),
@@ -63,12 +60,12 @@ const countLines = ($el) =>
  * add a tooltip to show extra information on hover
  * @param {HTMLElement} $ref - the element that will trigger the tooltip when hovered
  * @param {string|HTMLElement} $content - markdown or element content of the tooltip
- * @param {object=} [options] - configuration of how the tooltip should be displayed
- * @param {number} [options.delay] - the amount of time in ms the element needs to be hovered over
+ * @param {object=} options - configuration of how the tooltip should be displayed
+ * @param {number=} options.delay - the amount of time in ms the element needs to be hovered over
  * for the tooltip to be shown (default: 100)
- * @param {string} [options.offsetDirection] - which side of the element the tooltip
+ * @param {string=} options.offsetDirection - which side of the element the tooltip
  * should be shown on: 'top', 'bottom', 'left' or 'right' (default: 'bottom')
- * @param {number} [options.maxLines] - the max number of lines that the content may be wrapped
+ * @param {number=} options.maxLines - the max number of lines that the content may be wrapped
  * to, used to position and size the tooltip correctly (default: 1)
  */
 export const addTooltip = async (
@@ -94,7 +91,7 @@ export const addTooltip = async (
     </div>`;
 
   let displayDelay;
-  $ref.addEventListener('mouseover', async (event) => {
+  $ref.addEventListener('mouseover', (_event) => {
     if (!displayDelay) {
       displayDelay = setTimeout(async () => {
         if ($ref.matches(':hover')) {
@@ -111,7 +108,7 @@ export const addTooltip = async (
     }
   });
 
-  $ref.addEventListener('mouseout', async (event) => {
+  $ref.addEventListener('mouseout', async (_event) => {
     displayDelay = undefined;
     if (_$tooltip.style.display === 'block' && !$ref.matches(':hover')) {
       await _$tooltip.animate([{ opacity: 1 }, { opacity: 0 }], { duration: 65 }).finished;
diff --git a/api/electron.mjs b/api/electron.mjs
index f39be56..1492333 100644
--- a/api/electron.mjs
+++ b/api/electron.mjs
@@ -8,14 +8,15 @@
 
 /**
  * access to electron renderer apis
- * @module notion-enhancer/api/env
+ * @namespace electron
  */
+import * as _api from './index.mjs'; // trick jsdoc
 
 /**
  * access to the electron BrowserWindow instance for the current window
  * see https://www.electronjs.org/docs/latest/api/browser-window
  * @type {BrowserWindow}
- * @runtime electron (renderer process)
+ * @process electron (renderer process)
  */
 export const browser = globalThis.__enhancerElectronApi?.browser;
 
@@ -23,7 +24,7 @@ export const browser = globalThis.__enhancerElectronApi?.browser;
  * access to the electron webFrame instance for the current page
  * see https://www.electronjs.org/docs/latest/api/web-frame
  * @type {webFrame}
- * @runtime electron (renderer process)
+ * @process electron (renderer process)
  */
 export const webFrame = globalThis.__enhancerElectronApi?.webFrame;
 
@@ -34,7 +35,7 @@ export const webFrame = globalThis.__enhancerElectronApi?.webFrame;
  * @param {string=} namespace - a prefix for the message to categorise
  * it as e.g. enhancer-related. this should not be changed unless replicating
  * builtin ipc events.
- * @runtime electron (renderer process)
+ * @process electron (renderer process)
  */
 export const sendMessage = (channel, data, namespace = 'notion-enhancer') => {
   if (globalThis.__enhancerElectronApi) {
@@ -49,7 +50,7 @@ export const sendMessage = (channel, data, namespace = 'notion-enhancer') => {
  * @param {string=} namespace - a prefix for the message to categorise
  * it as e.g. enhancer-related. this should not be changed unless replicating
  * builtin ipc events.
- * @runtime electron (renderer process)
+ * @process electron (renderer process)
  */
 export const sendMessageToHost = (channel, data, namespace = 'notion-enhancer') => {
   if (globalThis.__enhancerElectronApi) {
@@ -65,7 +66,7 @@ export const sendMessageToHost = (channel, data, namespace = 'notion-enhancer')
  * @param {string=} namespace - a prefix for the message to categorise
  * it as e.g. enhancer-related. this should not be changed unless replicating
  * builtin ipc events.
- * @runtime electron (renderer process)
+ * @process electron (renderer process)
  */
 export const onMessage = (channel, callback, namespace = 'notion-enhancer') => {
   if (globalThis.__enhancerElectronApi) {
@@ -76,7 +77,7 @@ export const onMessage = (channel, callback, namespace = 'notion-enhancer') => {
 /**
  * require() notion app files
  * @param {string} path - within notion/resources/app/ e.g. main/createWindow.js
- * @runtime electron (main process)
+ * @process electron (main process)
  */
 export const notionRequire = (path) => {
   return globalThis.__enhancerElectronApi
@@ -86,7 +87,7 @@ export const notionRequire = (path) => {
 
 /**
  * get all available app windows excluding the menu
- * @runtime electron (main process)
+ * @process electron (main process)
  */
 export const getNotionWindows = () => {
   return globalThis.__enhancerElectronApi
@@ -96,7 +97,7 @@ export const getNotionWindows = () => {
 
 /**
  * get the currently focused notion window
- * @runtime electron (main process)
+ * @process electron (main process)
  */
 export const getFocusedNotionWindow = () => {
   return globalThis.__enhancerElectronApi
diff --git a/api/env.mjs b/api/env.mjs
index 36598e6..27f3ac4 100644
--- a/api/env.mjs
+++ b/api/env.mjs
@@ -8,7 +8,7 @@
 
 /**
  * environment-specific methods and constants
- * @module notion-enhancer/api/env
+ * @namespace env
  */
 
 import * as env from '../env/env.mjs';
diff --git a/api/fmt.mjs b/api/fmt.mjs
index b19ec79..57660cb 100644
--- a/api/fmt.mjs
+++ b/api/fmt.mjs
@@ -8,16 +8,16 @@
 
 /**
  * helpers for formatting or parsing text
- * @module notion-enhancer/api/fmt
+ * @namespace fmt
  */
 
 import { fs } from './index.mjs';
 
 /**
- * transform a heading into a slug (a lowercase alphanumeric string separated by dashes),
+ * transform a heading into a slug (a lowercase alphanumeric string separated by hyphens),
  * e.g. for use as an anchor id
  * @param {string} heading - the original heading to be slugified
- * @param {Set<string>} [slugs] - a list of pre-generated slugs to avoid duplicates
+ * @param {Set<string>=} slugs - a list of pre-generated slugs to avoid duplicates
  * @returns {string} the generated slug
  */
 export const slugger = (heading, slugs = new Set()) => {
@@ -49,26 +49,25 @@ export const uuidv4 = () => {
 /**
  * log-based shading of an rgb color, from
  * https://stackoverflow.com/questions/5560248/programmatically-lighten-or-darken-a-hex-color-or-rgb-and-blend-colors
- * @param {number} p - a decimal amount to shade the color.
+ * @param {number} shade - a decimal amount to shade the color.
  * 1 = white, 0 = the original color, -1 = black
- * @param {string} c - the rgb color
+ * @param {string} color - the rgb color
  * @returns {string} the shaded color
  */
-export const rgbLogShade = (p, c) => {
-  const i = parseInt,
-    r = Math.round,
-    [a, b, c, d] = c.split(','),
-    P = p < 0,
-    t = P ? 0 : p * 255 ** 2,
-    P = P ? 1 + p : 1 - p;
+export const rgbLogShade = (shade, color) => {
+  const int = parseInt,
+    round = Math.round,
+    [a, b, c, d] = color.split(','),
+    t = shade < 0 ? 0 : shade * 255 ** 2,
+    p = shade < 0 ? 1 + shade : 1 - shade;
   return (
     'rgb' +
     (d ? 'a(' : '(') +
-    r((P * i(a[3] == 'a' ? a.slice(5) : a.slice(4)) ** 2 + t) ** 0.5) +
+    round((p * int(a[3] == 'a' ? a.slice(5) : a.slice(4)) ** 2 + t) ** 0.5) +
     ',' +
-    r((P * i(b) ** 2 + t) ** 0.5) +
+    round((p * int(b) ** 2 + t) ** 0.5) +
     ',' +
-    r((P * i(c) ** 2 + t) ** 0.5) +
+    round((p * int(c) ** 2 + t) ** 0.5) +
     (d ? ',' + d : ')')
   );
 };
@@ -104,8 +103,8 @@ function test(str, pattern) {
 
 /**
  * test the type of a value. unifies builtin, regex, and environment/api checks
- * @param {*} value - the value to check
- * @param {string|array<values>} type - the type the value should be or a list of allowed values
+ * @param {unknown} value - the value to check
+ * @param {string|string[]} type - the type the value should be or a list of allowed values
  * @returns {boolean} whether or not the value matches the type
  */
 export const is = async (value, type, { extension = '' } = {}) => {
diff --git a/api/fs.mjs b/api/fs.mjs
index 86dd027..fa18d7b 100644
--- a/api/fs.mjs
+++ b/api/fs.mjs
@@ -8,7 +8,7 @@
 
 /**
  * environment-specific file reading
- * @module notion-enhancer/api/fs
+ * @namespace fs
  */
 
 import * as fs from '../env/fs.mjs';
@@ -16,7 +16,7 @@ import * as fs from '../env/fs.mjs';
 /**
  * get an absolute path to files within notion
  * @param {string} path - relative to the root notion/resources/app/ e.g. renderer/search.js
- * @runtime electron
+ * @process electron
  */
 export const notionPath = fs.notionPath;
 
@@ -32,8 +32,8 @@ export const localPath = fs.localPath;
  * fetch and parse a json file's contents
  * @type {function}
  * @param {string} path - a url or within-the-enhancer filepath
- * @param {object} [opts] - the second argument of a fetch() request
- * @returns {object} the json value of the requested file as a js object
+ * @param {FetchOptions=} opts - the second argument of a fetch() request
+ * @returns {unknown} the json value of the requested file as a js object
  */
 export const getJSON = fs.getJSON;
 
@@ -41,7 +41,7 @@ export const getJSON = fs.getJSON;
  * fetch a text file's contents
  * @type {function}
  * @param {string} path - a url or within-the-enhancer filepath
- * @param {object} [opts] - the second argument of a fetch() request
+ * @param {FetchOptions=} opts - the second argument of a fetch() request
  * @returns {string} the text content of the requested file
  */
 export const getText = fs.getText;
diff --git a/api/index.mjs b/api/index.mjs
index 8fdfab8..f3538f8 100644
--- a/api/index.mjs
+++ b/api/index.mjs
@@ -6,8 +6,6 @@
 
 'use strict';
 
-/** @module notion-enhancer/api */
-
 // compiles to .cjs for use in electron:
 // npx -y esbuild insert/api/index.mjs --minify --bundle --format=cjs --outfile=insert/api/index.cjs
 
diff --git a/api/notion.mjs b/api/notion.mjs
index a6996eb..8757ba4 100644
--- a/api/notion.mjs
+++ b/api/notion.mjs
@@ -8,7 +8,7 @@
 
 /**
  * a basic wrapper around notion's content apis
- * @module notion-enhancer/api/notion
+ * @namespace notion
  */
 
 import { web, fs, fmt } from './index.mjs';
@@ -30,7 +30,7 @@ const standardiseUUID = (uuid) => {
  * 1. cors blocking prevents use on the client
  * 2. the majority of blocks are still 'unsupported'
  * @param {string} id - uuidv4 record id
- * @param {string} [table] - record type (default: 'block').
+ * @param {string=} table - record type (default: 'block').
  * may also be 'collection', 'collection_view', 'space', 'notion_user', 'discussion', or 'comment'
  * @returns {Promise<object>} record data. type definitions can be found here:
  * https://github.com/NotionX/react-notion-x/tree/master/packages/notion-types/src
@@ -79,9 +79,9 @@ export const getSpaceID = async () => {
  * why not use the official api?
  * 1. cors blocking prevents use on the client
  * 2. the majority of blocks are still 'unsupported'
- * @param {string} [query] - query to search blocks in the space for
- * @param {number} [limit] - the max number of results to return (default: 20)
- * @param {string} [spaceID] - uuidv4 workspace id
+ * @param {string=} query - query to search blocks in the space for
+ * @param {number=} limit - the max number of results to return (default: 20)
+ * @param {string=} spaceID - uuidv4 workspace id
  * @returns {object} the number of total results, the list of matches, and related record values.
  * type definitions can be found here: https://github.com/NotionX/react-notion-x/blob/master/packages/notion-types/src/api.ts
  */
@@ -142,14 +142,14 @@ export const search = async (query = '', limit = 20, spaceID = getSpaceID()) =>
  * then find the value of blockRecord.properties.title using notion.get.
  * type definitions can be found here: https://github.com/NotionX/react-notion-x/blob/master/packages/notion-types/src/core.ts
  * @param {string} pointer.recordID - uuidv4 record id
- * @param {string} [pointer.recordTable] - record type (default: 'block').
+ * @param {string=} pointer.recordTable - record type (default: 'block').
  * may also be 'collection', 'collection_view', 'space', 'notion_user', 'discussion', or 'comment'
- * @param {string} [pointer.property] - the record property to update.
+ * @param {string=} pointer.property - the record property to update.
  * for record content, it will be the default: 'title'.
  * for page properties, it will be the property id (the key used in pageRecord.properties).
  * other possible values are unknown/untested
- * @param {string} [pointer.spaceID] - uuidv4 workspace id
- * @param {string} [pointer.path] - the path to the key to be set within the record
+ * @param {string=} pointer.spaceID - uuidv4 workspace id
+ * @param {string=} pointer.path - the path to the key to be set within the record
  * (default: [], the root of the record's values)
  * @returns {boolean|object} true if success, else an error object
  */
@@ -202,16 +202,16 @@ export const set = async (
  * for examples, use notion.get to fetch an existing block record.
  * type definitions can be found here: https://github.com/NotionX/react-notion-x/blob/master/packages/notion-types/src/block.ts
  * may also be 'collection', 'collection_view', 'space', 'notion_user', 'discussion', or 'comment'
- * @param {object} [insert.recordValue] - the new raw data values to set to the record.
- * @param {object} [insert.recordTable] - record type (default: 'block').
+ * @param {object=} insert.recordValue - the new raw data values to set to the record.
+ * @param {object=} insert.recordTable - record type (default: 'block').
  * may also be 'collection', 'collection_view', 'space', 'notion_user', 'discussion', or 'comment'
- * @param {string} [pointer.prepend] - insert before pointer.siblingID. if false, will be appended after
- * @param {string} [pointer.siblingID] - uuidv4 sibling id. if unset, the record will be
+ * @param {string=} pointer.prepend - insert before pointer.siblingID. if false, will be appended after
+ * @param {string=} pointer.siblingID - uuidv4 sibling id. if unset, the record will be
  * inserted at the end of the page start (or the start if pointer.prepend is true)
- * @param {string} [pointer.parentID] - uuidv4 parent id
- * @param {string} [pointer.parentTable] - parent record type (default: 'block').
- * @param {string} [pointer.spaceID] - uuidv4 space id
- * @param {string} [pointer.userID] - uuidv4 user id
+ * @param {string=} pointer.parentID - uuidv4 parent id
+ * @param {string=} pointer.parentTable - parent record type (default: 'block').
+ * @param {string=} pointer.spaceID - uuidv4 space id
+ * @param {string=} pointer.userID - uuidv4 user id
  * instead of the end
  * @returns {string|object} error object or uuidv4 of the new record
  */
@@ -313,9 +313,9 @@ export const create = async (
  * 1. cors blocking prevents use on the client
  * 2. the majority of blocks are still 'unsupported'
  * @param {File} file - the file to upload
- * @param {object} [pointer] - where the file should be accessible from
- * @param {string} [pointer.pageID] - uuidv4 page id
- * @param {string} [pointer.spaceID] - uuidv4 space id
+ * @param {object=} pointer - where the file should be accessible from
+ * @param {string=} pointer.pageID - uuidv4 page id
+ * @param {string=} pointer.spaceID - uuidv4 space id
  * @returns {string|object} error object or the url of the uploaded file
  */
 export const upload = async (file, { pageID = getPageID(), spaceID = getSpaceID() } = {}) => {
@@ -351,7 +351,7 @@ export const upload = async (file, { pageID = getPageID(), spaceID = getSpaceID(
  * (requires user to be signed in or content to be public)
  * @param src source url for file
  * @param {string} recordID uuidv4 record/block/file id
- * @param {string} [recordTable] record type (default: 'block').
+ * @param {string=} recordTable record type (default: 'block').
  * may also be 'collection', 'collection_view', 'space', 'notion_user', 'discussion', or 'comment'
  * @returns {string} url signed if necessary, else string as-is
  */
diff --git a/api/registry-validation.mjs b/api/registry-validation.mjs
index d467e8a..1b032d2 100644
--- a/api/registry-validation.mjs
+++ b/api/registry-validation.mjs
@@ -85,7 +85,7 @@ const validateEnvironments = async (mod) => {
     const isArray = await check(mod, 'css', mod.css, 'object');
     if (!isArray) return false;
     const tests = [];
-    for (let dest of ['frame', 'client', 'menu']) {
+    for (const dest of ['frame', 'client', 'menu']) {
       if (!mod.css[dest]) continue;
       let test = await check(mod, `css.${dest}`, mod.css[dest], 'array');
       if (test) {
@@ -101,7 +101,7 @@ const validateEnvironments = async (mod) => {
     const isArray = await check(mod, 'js', mod.js, 'object');
     if (!isArray) return false;
     const tests = [];
-    for (let dest of ['frame', 'client', 'menu']) {
+    for (const dest of ['frame', 'client', 'menu']) {
       if (!mod.js[dest]) continue;
       let test = await check(mod, `js.${dest}`, mod.js[dest], 'array');
       if (test) {
diff --git a/api/registry.mjs b/api/registry.mjs
index cc667e6..4c2682b 100644
--- a/api/registry.mjs
+++ b/api/registry.mjs
@@ -8,7 +8,7 @@
 
 /**
  * interactions with the enhancer's repository of mods
- * @module notion-enhancer/api/registry
+ * @namespace registry
  */
 
 import { env, fs, storage } from './index.mjs';
@@ -17,7 +17,7 @@ import { validate } from './registry-validation.mjs';
 /**
  * mod ids whitelisted as part of the enhancer's core, permanently enabled
  * @constant
- * @type {array<string>}
+ * @type {string[]}
  */
 export const core = [
   'a6621988-551d-495a-97d8-3c568bca2e9e',
@@ -28,14 +28,14 @@ export const core = [
 /**
  * all environments/platforms currently supported by the enhancer
  * @constant
- * @type {array<string>}
+ * @type {string[]}
  */
 export const supportedEnvs = ['linux', 'win32', 'darwin', 'extension'];
 
 /**
  * all available configuration types
  * @constant
- * @type {array<string>}
+ * @type {string[]}
  */
 export const optionTypes = ['toggle', 'select', 'text', 'number', 'color', 'file', 'hotkey'];
 
@@ -43,7 +43,7 @@ export const optionTypes = ['toggle', 'select', 'text', 'number', 'color', 'file
  * the name of the active configuration profile
  * @returns {string}
  */
-export const profileName = async () => storage.get(['currentprofile'], 'default');
+export const profileName = () => storage.get(['currentprofile'], 'default');
 
 /**
  * the root database for the current profile
@@ -51,8 +51,8 @@ export const profileName = async () => storage.get(['currentprofile'], 'default'
  */
 export const profileDB = async () => storage.db(['profiles', await profileName()]);
 
-let _list,
-  _errors = [];
+let _list;
+const _errors = [];
 /**
  * list all available mods in the repo
  * @param {function} filter - a function to filter out mods
@@ -60,7 +60,8 @@ let _list,
  */
 export const list = async (filter = (mod) => true) => {
   if (!_list) {
-    _list = new Promise(async (res, rej) => {
+    // deno-lint-ignore no-async-promise-executor
+    _list = new Promise(async (res, _rej) => {
       const passed = [];
       for (const dir of await fs.getJSON('repo/registry.json')) {
         try {
@@ -84,7 +85,7 @@ export const list = async (filter = (mod) => true) => {
 
 /**
  * list validation errors encountered when loading the repo
- * @returns {array<object>} error objects with an error message and a source directory
+ * @returns {{ source: string, message: string }[]} error objects with an error message and a source directory
  */
 export const errors = async () => {
   await list();
diff --git a/api/storage.mjs b/api/storage.mjs
index 9d62c5b..8c7dc31 100644
--- a/api/storage.mjs
+++ b/api/storage.mjs
@@ -8,7 +8,7 @@
 
 /**
  * environment-specific data persistence
- * @module notion-enhancer/api/storage
+ * @namespace storage
  */
 
 import * as storage from '../env/storage.mjs';
@@ -16,8 +16,8 @@ import * as storage from '../env/storage.mjs';
 /**
  * get persisted data
  * @type {function}
- * @param {array<string>} path - the path of keys to the value being fetched
- * @param {*} [fallback] - a default value if the path is not matched
+ * @param {string[]} path - the path of keys to the value being fetched
+ * @param {unknown=} fallback - a default value if the path is not matched
  * @returns {Promise} value ?? fallback
  */
 export const get = storage.get;
@@ -25,8 +25,8 @@ export const get = storage.get;
 /**
  * persist data
  * @type {function}
- * @param {array<string>} path - the path of keys to the value being set
- * @param {*} value - the data to save
+ * @param {string[]} path - the path of keys to the value being set
+ * @param {unknown} value - the data to save
  * @returns {Promise} resolves when data has been saved
  */
 export const set = storage.set;
@@ -34,9 +34,9 @@ export const set = storage.set;
 /**
  * create a wrapper for accessing a partition of the storage
  * @type {function}
- * @param {array<string>} namespace - the path of keys to prefix all storage requests with
- * @param {function} [get] - the storage get function to be wrapped
- * @param {function} [set] - the storage set function to be wrapped
+ * @param {string[]} namespace - the path of keys to prefix all storage requests with
+ * @param {function=} get - the storage get function to be wrapped
+ * @param {function=} set - the storage set function to be wrapped
  * @returns {object} an object with the wrapped get/set functions
  */
 export const db = storage.db;
@@ -60,6 +60,6 @@ export const removeChangeListener = storage.removeChangeListener;
  * @callback onStorageChangeCallback
  * @param {object} event
  * @param {string} event.path- the path of keys to the changed value
- * @param {string} [event.new] - the new value being persisted to the store
- * @param {string} [event.old] - the previous value associated with the key
+ * @param {string=} event.new - the new value being persisted to the store
+ * @param {string=} event.old - the previous value associated with the key
  */
diff --git a/api/web.mjs b/api/web.mjs
index b247f3c..8b201e0 100644
--- a/api/web.mjs
+++ b/api/web.mjs
@@ -8,7 +8,7 @@
 
 /**
  * helpers for manipulation of a webpage
- * @module notion-enhancer/api/web
+ * @namespace web
  */
 
 import { fs } from './index.mjs';
@@ -16,16 +16,16 @@ import { fs } from './index.mjs';
 let _hotkeyListenersActivated = false,
   _hotkeyEventListeners = [],
   _documentObserver,
-  _documentObserverListeners = [],
-  _documentObserverEvents = [];
+  _documentObserverListeners = [];
+const _documentObserverEvents = [];
 
 /**
  * wait until a page is loaded and ready for modification
- * @param {array} [selectors] - wait for the existence of elements that match these css selectors
+ * @param {array=} selectors - wait for the existence of elements that match these css selectors
  * @returns {Promise} a promise that will resolve when the page is ready
  */
 export const whenReady = (selectors = []) => {
-  return new Promise((res, rej) => {
+  return new Promise((res, _rej) => {
     const onLoad = () => {
       const interval = setInterval(isReady, 100);
       function isReady() {
@@ -37,7 +37,7 @@ export const whenReady = (selectors = []) => {
       isReady();
     };
     if (document.readyState !== 'complete') {
-      document.addEventListener('readystatechange', (event) => {
+      document.addEventListener('readystatechange', (_event) => {
         if (document.readyState === 'complete') onLoad();
       });
     } else onLoad();
@@ -46,7 +46,7 @@ export const whenReady = (selectors = []) => {
 
 /**
  * parse the current location search params into a usable form
- * @returns {map<string,string>} a map of the url search params
+ * @returns {Map<string, string>} a map of the url search params
  */
 export const queryParams = () => new URLSearchParams(window.location.search);
 
@@ -207,10 +207,10 @@ const triggerHotkeyListener = (event, hotkey) => {
  * available modifiers are 'alt', 'ctrl', 'meta', and 'shift'.
  * can be provided as a + separated string.
  * @param {function} callback - called whenever the keys are pressed
- * @param {object} [opts] - fine-tuned control over when the hotkey should be triggered
- * @param {boolean} [opts.listenInInput] - whether the hotkey callback should be triggered
+ * @param {object=} opts - fine-tuned control over when the hotkey should be triggered
+ * @param {boolean=} opts.listenInInput - whether the hotkey callback should be triggered
  * when an input is focused
- * @param {boolean} [opts.keydown] - whether to listen for the hotkey on keydown.
+ * @param {boolean=} opts.keydown - whether to listen for the hotkey on keydown.
  * by default, hotkeys are triggered by the keyup event.
  */
 export const addHotkeyListener = (
@@ -248,7 +248,7 @@ export const removeHotkeyListener = (callback) => {
 /**
  * add a listener to watch for changes to the dom
  * @param {onDocumentObservedCallback} callback
- * @param {array<string>} [selectors]
+ * @param {string[]=} selectors
  */
 export const addDocumentObserver = (callback, selectors = []) => {
   if (!_documentObserver) {
@@ -271,7 +271,7 @@ export const addDocumentObserver = (callback, selectors = []) => {
         }
       }
     };
-    _documentObserver = new MutationObserver((list, observer) => {
+    _documentObserver = new MutationObserver((list, _observer) => {
       if (!_documentObserverEvents.length)
         requestIdleCallback(() => handle(_documentObserverEvents));
       _documentObserverEvents.push(...list);