redesigned how DOM types are handled for TS/JSDoc

embed_component.js

···
     this.embed = embed;
   }
 
-  /** @returns {AnyElement} */
+  /** @returns {HTMLElement} */
 
   buildElement() {
     if (this.embed instanceof RawRecordEmbed) {
···
     }
   }
 
-  /** @returns {AnyElement} */
+  /** @returns {HTMLElement} */
 
   quotedPostPlaceholder() {
     return $tag('div.quote-embed', {
···
     });
   }
 
-  /** @param {InlineRecordEmbed | InlineRecordWithMediaEmbed} embed, @returns {AnyElement} */
+  /** @param {InlineRecordEmbed | InlineRecordWithMediaEmbed} embed, @returns {HTMLElement} */
 
   buildQuotedPostElement(embed) {
     let div = $tag('div.quote-embed');
···
     return div;
   }
 
-  /** @params {RawLinkEmbed | InlineLinkEmbed} embed, @returns {AnyElement} */
+  /** @params {RawLinkEmbed | InlineLinkEmbed} embed, @returns {HTMLElement} */
 
   buildLinkComponent(embed) {
     let hostname;
···
     return a;
   }
 
-  /** @param {FeedGeneratorRecord} feedgen, @returns {AnyElement} */
+  /** @param {FeedGeneratorRecord} feedgen, @returns {HTMLElement} */
 
   buildFeedGeneratorView(feedgen) {
     let link = this.linkToFeedGenerator(feedgen);
···
     let box = $tag('div');
 
     if (feedgen.avatar) {
-      let avatar = $tag('img.avatar');
+      let avatar = $tag('img.avatar', HTMLImageElement);
       avatar.src = feedgen.avatar;
       box.append(avatar);
     }
···
     return `https://bsky.app/profile/${repo}/feed/${rkey}`;
   }
 
-  /** @param {UserListRecord} list, @returns {AnyElement} */
+  /** @param {UserListRecord} list, @returns {HTMLElement} */
 
   buildUserListView(list) {
     let link = this.linkToUserList(list);
···
     let box = $tag('div');
 
     if (list.avatar) {
-      let avatar = $tag('img.avatar');
+      let avatar = $tag('img.avatar', HTMLImageElement);
       avatar.src = list.avatar;
       box.append(avatar);
     }
···
     return a;
   }
 
-  /** @param {StarterPackRecord} pack, @returns {AnyElement} */
+  /** @param {StarterPackRecord} pack, @returns {HTMLElement} */
 
   buildStarterPackView(pack) {
     let { repo, rkey } = atURI(pack.uri);
···
     return `https://bsky.app/profile/${repo}/lists/${rkey}`;
   }
 
-  /** @params {RawImageEmbed | InlineImageEmbed} embed, @returns {AnyElement} */
+  /** @params {RawImageEmbed | InlineImageEmbed} embed, @returns {HTMLElement} */
 
   buildImagesComponent(embed) {
     let wrapper = $tag('div');
···
       p.append('[');
 
       // TODO: load image
-      let a = $tag('a', { text: "Image" });
+      let a = $tag('a', { text: "Image" }, HTMLLinkElement);
 
       if (image.fullsize) {
         a.href = image.fullsize;
···
     return wrapper;
   }
 
-  /** @params {RawVideoEmbed | InlineVideoEmbed} embed, @returns {AnyElement} */
+  /** @params {RawVideoEmbed | InlineVideoEmbed} embed, @returns {HTMLElement} */
 
   buildVideoComponent(embed) {
     let wrapper = $tag('div');
 
     // TODO: load thumbnail
-    let a = $tag('a', { text: "Video" });
+    let a = $tag('a', { text: "Video" }, HTMLLinkElement);
 
     if (embed.playlistURL) {
       a.href = embed.playlistURL;
···
     return wrapper;
   }
 
-  /** @param {string} uri, @param {AnyElement} div, @returns Promise<void> */
+  /** @param {string} uri, @param {HTMLElement} div, @returns Promise<void> */
 
   async loadQuotedPost(uri, div) {
     let record = await api.loadPostIfExists(uri);

post_component.js

···
 class PostComponent {
   /**
    * Post component's root HTML element, if built.
-   * @type {AnyElement | undefined}
+   * @type {HTMLElement | undefined}
    */
   _rootElement;
 
···
   }
 
   /**
-   * @returns {AnyElement}
+   * @returns {HTMLElement}
    */
   get rootElement() {
     if (!this._rootElement) {
···
     }
   }
 
-  /** @param {AnyElement} nodeToUpdate */
+  /** @param {HTMLElement} nodeToUpdate */
   installIntoElement(nodeToUpdate) {
     let view = this.buildElement();
 
-    nodeToUpdate.querySelector('.content').replaceWith(view.querySelector('.content'));
+    let oldContent = $(nodeToUpdate.querySelector('.content'));
+    let newContent = $(view.querySelector('.content'));
+    oldContent.replaceWith(newContent);
+
     this._rootElement = nodeToUpdate;
   }
 
-  /** @returns {AnyElement} */
+  /** @returns {HTMLElement} */
   buildElement() {
     if (this._rootElement) {
       return this._rootElement;
···
     return div;
   }
 
-  /** @returns {AnyElement} */
+  /** @returns {HTMLElement} */
 
   buildPostHeader() {
     let timeFormat = this.timeFormatForTimestamp;
···
   /** @param {string} url, @returns {HTMLImageElement} */
 
   buildUserAvatar(url) {
-    let avatar = $tag('img.avatar', { loading: 'lazy' }); // needs to be set before src!
+    let avatar = $tag('img.avatar', { loading: 'lazy' }, HTMLImageElement); // needs to be set before src!
     avatar.src = url;
     window.avatarPreloader.observe(avatar);
     return avatar;
   }
 
-  /** @returns {AnyElement} */
+  /** @returns {HTMLElement} */
 
   buildPostBody() {
     if (this.post.originalFediContent) {
···
     return p;
   }
 
-  /** @param {string[]} tags, @returns {AnyElement} */
+  /** @param {string[]} tags, @returns {HTMLElement} */
 
   buildTagsRow(tags) {
     let p = $tag('p.tags');
···
     return p;
   }
 
-  /** @returns {AnyElement} */
+  /** @returns {HTMLElement} */
 
   buildStatsFooter() {
     let stats = $tag('p.stats');
···
     return stats;
   }
 
-  /** @param {number} count, @param {boolean} expanded, @returns {AnyElement} */
+  /** @param {number} count, @param {boolean} expanded, @returns {HTMLElement} */
 
   buildQuotesIconLink(count, expanded) {
     let q = new URL(getLocation());
···
   /** @param {number} quoteCount, @param {boolean} expanded */
 
   appendQuotesIconLink(quoteCount, expanded) {
-    let stats = this.rootElement.querySelector(':scope > .content > p.stats');
+    let stats = $(this.rootElement.querySelector(':scope > .content > p.stats'));
     let quotesLink = this.buildQuotesIconLink(quoteCount, expanded);
     stats.append(quotesLink);
   }
 
-  /** @returns {AnyElement} */
+  /** @returns {HTMLElement} */
 
   buildLoadMoreLink() {
     let loadMore = $tag('p');
···
     return loadMore;
   }
 
-  /** @returns {AnyElement} */
+  /** @returns {HTMLElement} */
 
   buildHiddenRepliesLink() {
     let loadMore = $tag('p.hidden-replies');
···
     return loadMore;
   }
 
-  /** @param {HTMLLinkElement} loadMoreButton */
+  /** @param {HTMLElement} loadMoreButton */
 
   loadHiddenReplies(loadMoreButton) {
     loadMoreButton.innerHTML = `<img class="loader" src="icons/sunny.png">`;
···
     });
   }
 
-  /** @param {AnyElement} div, @returns {AnyElement} */
+  /** @param {HTMLElement} div, @returns {HTMLElement} */
 
   buildBlockedPostElement(div) {
     let p = $tag('p.blocked-header');
···
     let blockStatus = this.post.blockedByUser ? 'has blocked you' : this.post.blocksUser ? "you've blocked them" : '';
     blockStatus = blockStatus ? `, ${blockStatus}` : '';
 
-    let authorLink = $tag('a', { href: this.didLinkToAuthor, target: '_blank', text: 'see author' });
+    let authorLink = $tag('a', { href: this.didLinkToAuthor, target: '_blank', text: 'see author' }, HTMLLinkElement);
     p.append(' (', authorLink, blockStatus, ') ');
     div.appendChild(p);
 
···
     return div;
   }
 
-  /** @param {AnyElement} div, @returns {AnyElement} */
+  /** @param {HTMLElement} div, @returns {HTMLElement} */
 
   buildDetachedQuoteElement(div) {
     let p = $tag('p.blocked-header');
···
       return p;
     }
 
-    let authorLink = $tag('a', { href: this.didLinkToAuthor, target: '_blank', text: 'see author' });
+    let authorLink = $tag('a', { href: this.didLinkToAuthor, target: '_blank', text: 'see author' }, HTMLLinkElement);
     p.append(' (', authorLink, ') ');
     div.appendChild(p);
 
···
     return div;
   }
 
-  /** @param {AnyElement} div, @returns {AnyElement} */
+  /** @param {HTMLElement} div, @returns {HTMLElement} */
 
   buildMissingPostElement(div) {
     let p = $tag('p.blocked-header');
     p.innerHTML = `<i class="fa-solid fa-ban"></i> <span>Deleted post</span>`;
 
-    let authorLink = $tag('a', { href: this.didLinkToAuthor, target: '_blank', text: 'see author' });
+    let authorLink = $tag('a', { href: this.didLinkToAuthor, target: '_blank', text: 'see author' }, HTMLLinkElement);
     p.append(' (', authorLink, ') ');
 
     this.loadReferencedPostAuthor(authorLink);
···
     return div;
   }
 
-  /** @param {string} uri, @param {AnyElement} div, @returns Promise<void> */
+  /** @param {string} uri, @param {HTMLElement} div, @returns Promise<void> */
 
   async loadBlockedPost(uri, div) {
     let record = await appView.loadPostIfExists(this.post.uri);
···
         html: `<i class="fa-solid fa-arrows-split-up-and-left fa-rotate-180"></i>`
       });
 
-      let header = div.querySelector('p.blocked-header');
+      let header = $(div.querySelector('p.blocked-header'));
       let separator = $tag('span.separator', { html: '&bull;' });
       header.append(separator, ' ', a);
     }
 
-    div.querySelector('p.load-post').remove();
+    let loadPost = $(div.querySelector('p.load-post'));
+    loadPost.remove();
 
     if (this.isRoot && this.post.parentReference) {
       let { repo, rkey } = atURI(this.post.parentReference.uri);
···
   }
 
   toggleSectionFold() {
-    let plus = this.rootElement.querySelector(':scope > .margin .plus');
+    let plus = $(this.rootElement.querySelector(':scope > .margin .plus'), HTMLImageElement);
 
     if (this.isCollapsed()) {
       this.rootElement.classList.remove('collapsed');
···
     }
   }
 
-  /** @param {AnyElement} heart */
+  /** @param {HTMLElement} heart */
 
   onHeartClick(heart) {
     if (!this.post.hasViewerInfo) {
···
       return;
     }
 
-    let count = heart.nextElementSibling;
+    let count = $(heart.nextElementSibling);
 
     if (!heart.classList.contains('liked')) {
       accountAPI.likePost(this.post).then((like) => {

skythread.js

···
 function init() {
-  let document = /** @type {AnyElement} */ (/** @type {unknown} */ (window.document));
-  let html = /** @type {AnyElement} */ (/** @type {unknown} */ (window.document.body.parentNode));
+  let html = $(document.body.parentNode);
 
   window.dateLocale = localStorage.getItem('locale') || undefined;
   window.isIncognito = !!localStorage.getItem('incognito');
   window.biohazardEnabled = JSON.parse(localStorage.getItem('biohazard') ?? 'null');
 
-  window.loginDialog = document.querySelector('#login');
-  window.accountMenu = document.querySelector('#account_menu');
+  window.loginDialog = $(document.querySelector('#login'));
+  window.accountMenu = $(document.querySelector('#account_menu'));
 
   window.avatarPreloader = buildAvatarPreloader();
 
···
     $id('account_menu').style.visibility = 'hidden';
   });
 
-  document.querySelector('#search form').addEventListener('submit', (e) => {
+  $(document.querySelector('#search form')).addEventListener('submit', (e) => {
     e.preventDefault();
     submitSearch();
   });
···
     });
   }
 
-  document.querySelector('#login .info a').addEventListener('click', (e) => {
+  $(document.querySelector('#login .info a')).addEventListener('click', (e) => {
     e.preventDefault();
     toggleLoginInfo();
   });
 
-  document.querySelector('#login form').addEventListener('submit', (e) => {
+  $(document.querySelector('#login form')).addEventListener('submit', (e) => {
     e.preventDefault();
     submitLogin();
   });
 
-  document.querySelector('#biohazard_show').addEventListener('click', (e) => {
+  $(document.querySelector('#biohazard_show')).addEventListener('click', (e) => {
     e.preventDefault();
 
     window.biohazardEnabled = true;
···
       window.loadInfohazard = undefined;
     }
 
-    let target = /** @type {AnyElement} */ (/** @type {unknown} */ (e.target));
+    let target = $(e.target);
 
     hideDialog(target.closest('.dialog'));
   });
 
-  document.querySelector('#biohazard_hide').addEventListener('click', (e) => {
+  $(document.querySelector('#biohazard_hide')).addEventListener('click', (e) => {
     e.preventDefault();
 
     window.biohazardEnabled = false;
···
     toggleMenuButton('biohazard', false);
 
     for (let p of document.querySelectorAll('p.hidden-replies, .content > .post.blocked, .blocked > .load-post')) {
-      p.style.display = 'none';
+      $(p).style.display = 'none';
     }
 
-    let target = /** @type {AnyElement} */ (/** @type {unknown} */ (e.target));
+    let target = $(e.target);
 
     hideDialog(target.closest('.dialog'));
   });
 
-  document.querySelector('#account').addEventListener('click', (e) => {
+  $(document.querySelector('#account')).addEventListener('click', (e) => {
     toggleAccountMenu();
     e.stopPropagation();
   });
···
     e.stopPropagation();
   });
 
-  accountMenu.querySelector('a[data-action=biohazard]').addEventListener('click', (e) => {
+  $(accountMenu.querySelector('a[data-action=biohazard]')).addEventListener('click', (e) => {
     e.preventDefault();
 
     let hazards = document.querySelectorAll('p.hidden-replies, .content > .post.blocked, .blocked > .load-post');
···
       window.biohazardEnabled = true;
       localStorage.setItem('biohazard', 'true');
       toggleMenuButton('biohazard', true);
-      Array.from(hazards).forEach(p => { p.style.display = 'block' });
+      Array.from(hazards).forEach(p => { $(p).style.display = 'block' });
     } else {
       window.biohazardEnabled = false;
       localStorage.setItem('biohazard', 'false');
       toggleMenuButton('biohazard', false);
-      Array.from(hazards).forEach(p => { p.style.display = 'none' });
+      Array.from(hazards).forEach(p => { $(p).style.display = 'none' });
     }
   });
 
-  accountMenu.querySelector('a[data-action=incognito]').addEventListener('click', (e) => {
+  $(accountMenu.querySelector('a[data-action=incognito]')).addEventListener('click', (e) => {
     e.preventDefault();
 
     if (isIncognito) {
···
     location.reload();
   });
 
-  accountMenu.querySelector('a[data-action=login]').addEventListener('click', (e) => {
+  $(accountMenu.querySelector('a[data-action=login]')).addEventListener('click', (e) => {
     e.preventDefault();
     toggleDialog(loginDialog);
     $id('account_menu').style.visibility = 'hidden';
   });
 
-  accountMenu.querySelector('a[data-action=logout]').addEventListener('click', (e) => {
+  $(accountMenu.querySelector('a[data-action=logout]')).addEventListener('click', (e) => {
     e.preventDefault();
     logOut();
   });
···
   }
 }
 
-/** @param {AnyPost} post, @returns {AnyElement} */
+/** @param {AnyPost} post, @returns {HTMLElement} */
 
 function buildParentLink(post) {
   let p = $tag('p.back');
···
   if (post instanceof BlockedPost) {
     let element = new PostComponent(post, 'parent').buildElement();
     element.className = 'back';
-    element.querySelector('p.blocked-header span').innerText = 'Parent post blocked';
+    let span = $(element.querySelector('p.blocked-header span'));
+    span.innerText = 'Parent post blocked';
     return element;
   } else if (post instanceof MissingPost) {
     p.innerHTML = `<i class="fa-solid fa-ban"></i> parent post has been deleted`;
···
 }
 
 function showSearch() {
-  $id('search').style.visibility = 'visible';
-  $id('search').querySelector('input[type=text]').focus();
+  let search = $id('search');
+  let searchField = $(search.querySelector('input[type=text]'));
+
+  search.style.visibility = 'visible';
+  searchField.focus();
 }
 
 function hideSearch() {
···
 /** @param {string} buttonName */
 
 function showMenuButton(buttonName) {
-  let button = accountMenu.querySelector(`a[data-action=${buttonName}]`);
-  button.parentNode.style.display = 'list-item';
+  let button = $(accountMenu.querySelector(`a[data-action=${buttonName}]`));
+  let item = $(button.parentNode);
+  item.style.display = 'list-item';
 }
 
 /** @param {string} buttonName */
 
 function hideMenuButton(buttonName) {
-  let button = accountMenu.querySelector(`a[data-action=${buttonName}]`);
-  button.parentNode.style.display = 'none';
+  let button = $(accountMenu.querySelector(`a[data-action=${buttonName}]`));
+  let item = $(button.parentNode);
+  item.style.display = 'none';
 }
 
 /** @param {string} buttonName, @param {boolean} state */
 
 function toggleMenuButton(buttonName, state) {
-  let button = accountMenu.querySelector(`a[data-action=${buttonName}]`);
-  button.querySelector('.check').style.display = (state) ? 'inline' : 'none';
+  let button = $(accountMenu.querySelector(`a[data-action=${buttonName}]`));
+  let check = $(button.querySelector('.check'));
+  check.style.display = (state) ? 'inline' : 'none';
 }
 
 /** @param {boolean | 'incognito'} loggedIn, @param {string | undefined | null} [avatar] */
···
   let account = $id('account');
 
   if (loggedIn === true && avatar) {
-    let button = account.querySelector('i');
+    let button = $(account.querySelector('i'));
 
     let img = $tag('img.avatar', { src: avatar });
     img.style.display = 'none';
···
 }
 
 function submitLogin() {
-  let handle = $id('login_handle');
-  let password = $id('login_password');
+  let handle = $id('login_handle', HTMLInputElement);
+  let password = $id('login_password', HTMLInputElement);
   let submit = $id('login_submit');
   let cloudy = $id('cloudy');
 
···
 }
 
 function submitSearch() {
-  let url = $id('search').querySelector('input[name=q]').value.trim();
+  let search = $id('search');
+  let searchField = $(search.querySelector('input[name=q]'), HTMLInputElement);
+  let url = searchField.value.trim();
 
   if (!url) { return }
 
···
   });
 }
 
-/** @param {Post} post, @param {AnyElement} nodeToUpdate */
+/** @param {Post} post, @param {HTMLElement} nodeToUpdate */
 
 function loadSubtree(post, nodeToUpdate) {
   api.loadThreadByAtURI(post.uri).then(json => {
···
   }).catch(showError);
 }
 
-/** @param {Post} post, @param {AnyElement} nodeToUpdate */
+/** @param {Post} post, @param {HTMLElement} nodeToUpdate */
 
 function loadHiddenSubtree(post, nodeToUpdate) {
-  let content = nodeToUpdate.querySelector('.content');
-  let hiddenRepliesDiv = content.querySelector(':scope > .hidden-replies');
+  let content = $(nodeToUpdate.querySelector('.content'));
+  let hiddenRepliesDiv = $(content.querySelector(':scope > .hidden-replies'));
 
   blueAPI.getReplies(post.uri).then(replies => {
     let missingReplies = replies.filter(r => !post.replies.some(x => x.uri === r));

types.d.ts

···
 declare var api: BlueskyAPI;
 declare var isIncognito: boolean;
 declare var biohazardEnabled: boolean;
-declare var loginDialog: AnyElement;
-declare var accountMenu: AnyElement;
+declare var loginDialog: HTMLElement;
+declare var accountMenu: HTMLElement;
 declare var avatarPreloader: IntersectionObserver;
 
-type SomeElement = Element | HTMLElement | AnyElement;
 type json = Record<string, any>;
 
-interface AnyElement {
-  classList: CSSClassList;
-  className: string;
-  innerText: string;
-  innerHTML: string;
-  nextElementSibling: AnyElement;
-  parentNode: AnyElement;
-  src: string;
-  style: CSSStyleDeclaration;
+function $tag(tag: string): HTMLElement;
+function $tag<T>(tag: string, type: new (...args: any[]) => T): T;
+function $tag(tag: string, params: string | object): HTMLElement;
+function $tag<T>(tag: string, params: string | object, type: new (...args: any[]) => T): T;
 
-  addEventListener<K extends keyof DocumentEventMap>(
-    type: K, listener: EventListenerOrEventListenerObject
-  ): void;
+function $id(id: string): HTMLElement;
+function $id<T>(id: string, type: new (...args: any[]) => T): T;
 
-  append(...e: Array<string | SomeElement>): void;
-  appendChild(e: SomeElement): void;
-  closest(q: string): AnyElement;
-  querySelector(q: string): AnyElement;
-  querySelectorAll(q: string): AnyElement[];
-  prepend(...e: Array<string | SomeElement>): void;
-  remove(): void;
-  replaceChildren(e: SomeElement): void;
-  replaceWith(e: SomeElement): void;
-}
+function $(element: Node | EventTarget | null): HTMLElement;
+function $<T>(element: Node | EventTarget | null, type: new (...args: any[]) => T): T;

utils.js

···
   }
 }
 
-/** @param {string} tag, @param {string | object} [params], @returns {any} */
+/**
+ * @template T
+ * @param {string} tag
+ * @param {string | object} params
+ * @param {new (...args: any[]) => T} type
+ * @returns {T}
+ */
 
-function $tag(tag, params) {
+function $tag(tag, params, type) {
   let element;
   let parts = tag.split('.');
 
···
     }
   }
 
-  return element;
+  return /** @type {T} */ (element);
+}
+
+function $id(name, type) {
+  return (document.getElementById(name));
 }
 
-/** @param {string} name, @returns {any} */
+/**
+ * @template T
+ * @param {Node | EventTarget | null} element
+ * @param {new (...args: any[]) => T} type
+ * @returns {T}
+ */
 
-function $id(name) {
-  return document.getElementById(name);
+function $(element, type) {
+  return /** @type {T} */ (element);
 }
 
 /** @param {string} uri, @returns {AtURI} */