convert from jsdoc to typescript with tsx

jest.config.js

···
 
 /** @type {jest_types.Config} */
 export default {
-  testMatch: ['<rootDir>/src/**/*.spec.{js,jsx}'],
+  testMatch: ['<rootDir>/src/**/*.spec.{ts,tsx}'],
   testPathIgnorePatterns: [
     ...gitignorePatterns(),
   ],
···
   ],
 
   collectCoverageFrom: [
-    'src/**/*.{js,jsx}',
-    '!src/**/*.spec.{js,jsx}',
+    'src/**/*.{ts,tsx}',
+    '!src/**/*.spec.{ts,tsx}',
     '!src/**/node_modules/**',
   ],
 }

package-lock.json

···
         "nanoid": "^5.1.5",
         "preact": "^10.26.9",
         "simple-peer": "^9.11.1",
+        "tsx": "^4.19.2",
         "ws": "^8.18.2",
         "zod": "~3.25"
       },
···
       "cpu": [
         "ppc64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
···
       "cpu": [
         "arm"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
···
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
···
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
···
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
···
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
···
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
···
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
···
       "cpu": [
         "arm"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
···
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
···
       "cpu": [
         "ia32"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
···
       "cpu": [
         "loong64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
···
       "cpu": [
         "mips64el"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
···
       "cpu": [
         "ppc64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
···
       "cpu": [
         "riscv64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
···
       "cpu": [
         "s390x"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
···
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
···
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
···
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
···
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
···
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
···
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
···
       "cpu": [
         "arm64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
···
       "cpu": [
         "ia32"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
···
       "cpu": [
         "x64"
       ],
-      "dev": true,
       "license": "MIT",
       "optional": true,
       "os": [
···
       "version": "0.25.5",
       "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.25.5.tgz",
       "integrity": "sha512-P8OtKZRv/5J5hhz0cUAdu/cLuPIKXpQl1R9pZtvmHWQvrAUVd0UNIPT4IB4W3rNOqVO0rlqHmCIbSwxh/c9yUQ==",
-      "dev": true,
       "hasInstallScript": true,
       "license": "MIT",
       "bin": {
···
       "version": "2.3.3",
       "resolved": "https://registry.npmjs.org/fsevents/-/fsevents-2.3.3.tgz",
       "integrity": "sha512-5xoDfX+fL7faATnagmWPpbFtwh/R77WmMMqqHGS65C3vvB0YHrgF+B1YmZ3441tMj5n63k0212XNoJwzlhffQw==",
-      "dev": true,
       "hasInstallScript": true,
       "license": "MIT",
       "optional": true,
···
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/get-tsconfig": {
+      "version": "4.10.1",
+      "resolved": "https://registry.npmjs.org/get-tsconfig/-/get-tsconfig-4.10.1.tgz",
+      "integrity": "sha512-auHyJ4AgMz7vgS8Hp3N6HXSmlMdUyhSUrfBF16w153rxtLIEOE+HGqaBppczZvnHLqQJfiHotCYpNhl0lUROFQ==",
+      "license": "MIT",
+      "dependencies": {
+        "resolve-pkg-maps": "^1.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/privatenumber/get-tsconfig?sponsor=1"
+      }
+    },
     "node_modules/github-from-package": {
       "version": "0.0.0",
       "resolved": "https://registry.npmjs.org/github-from-package/-/github-from-package-0.0.0.tgz",
···
         "node": ">=4"
       }
     },
+    "node_modules/resolve-pkg-maps": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/resolve-pkg-maps/-/resolve-pkg-maps-1.0.0.tgz",
+      "integrity": "sha512-seS2Tj26TBVOC2NIc2rOe2y2ZO7efxITtLZcGSOnHHNOQ7CkiUBfw0Iw2ck6xkIhPwLhKNLS8BO+hEpngQlqzw==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/privatenumber/resolve-pkg-maps?sponsor=1"
+      }
+    },
     "node_modules/ret": {
       "version": "0.2.2",
       "resolved": "https://registry.npmjs.org/ret/-/ret-0.2.2.tgz",
···
       "dev": true,
       "license": "0BSD",
       "optional": true
+    },
+    "node_modules/tsx": {
+      "version": "4.20.3",
+      "resolved": "https://registry.npmjs.org/tsx/-/tsx-4.20.3.tgz",
+      "integrity": "sha512-qjbnuR9Tr+FJOMBqJCW5ehvIo/buZq7vH7qD7JziU98h6l3qGy0a/yPFjwO+y0/T7GFpNgNAvEcPPVfyT8rrPQ==",
+      "license": "MIT",
+      "dependencies": {
+        "esbuild": "~0.25.0",
+        "get-tsconfig": "^4.7.5"
+      },
+      "bin": {
+        "tsx": "dist/cli.mjs"
+      },
+      "engines": {
+        "node": ">=18.0.0"
+      },
+      "optionalDependencies": {
+        "fsevents": "~2.3.3"
+      }
     },
     "node_modules/tty-browserify": {
       "version": "0.0.1",

package.json

···
     "nanoid": "^5.1.5",
     "preact": "^10.26.9",
     "simple-peer": "^9.11.1",
+    "tsx": "^4.19.2",
     "ws": "^8.18.2",
     "zod": "~3.25"
   },
···
     "build": {
       "command": "vite build",
       "files": [
-        "src/client/**/*.{js,jsx}",
-        "src/client/*.{js,jsx}",
-        "src/common/**/*.js",
-        "src/common/*.js",
-        "!src/**/*.spec.{js,jsx}"
+        "src/client/**/*.{ts,tsx}",
+        "src/client/*.{ts,tsx}",
+        "src/common/**/*.ts",
+        "src/common/*.ts",
+        "!src/**/*.spec.{ts,tsx}"
       ],
       "output": [
         "./dist/**"
···
     "lint": {
       "command": "eslint --color --cache --cache-location .eslintcache .",
       "files": [
-        "src/**/*.js",
+        "src/**/*.{ts,tsx}",
         "eslint.config.js",
         ".eslintignore"
       ],
···
     "test": {
       "command": "jest --cache --cacheDirectory .jestcache",
       "files": [
-        "src/**/*.js",
-        "src/**/*.jsx",
+        "src/**/*.{ts,tsx}",
         "jest.config.js",
         "jest.setup.js"
       ],
···
     "types": {
       "command": "tsc --build --pretty --noEmit",
       "files": [
-        "src/**/*.js",
+        "src/**/*.{ts,tsx}",
         "tsconfig.json"
       ],
       "output": [
···
     "docs": {
       "command": "jsdoc -c jsdoc.json",
       "files": [
-        "src/**/*.{js,jsx}",
-        "!src/**/*.spec.{js,jsx}",
+        "src/**/*.{ts,tsx}",
+        "!src/**/*.spec.{ts,tsx}",
         "jsdoc.json"
       ],
       "output": [
···
     },
     "run:server": {
       "service": true,
-      "command": "node --watch --watch-preserve-output src/cmd/server.js"
+      "command": "tsx --watch src/cmd/server.ts"
     },
     "start:tests": {
       "service": true,

src/client/components/messenger.jsx

···
-// @ts-nocheck
-
-import * as connection_types from '#client/realm/connection.js'
-import * as protocol_types from '#common/protocol.js'
-import { useState, useEffect, useCallback } from 'preact/hooks'
-
-/**
- * @param {object} props list props
- * @param {connection_types.RealmConnection} props.webrtcManager connection manager
- * @returns {preact.JSX.Element} the peerlist component
- */
-export function Messenger({ webrtcManager }) {
-  const [messages, setMessages] = useState(/** @type {Array<any>} */ [])
-
-  const peerdata = useCallback(
-    /** @type {function(CustomEvent): void} */
-    (event) => {
-      setMessages([...messages, [event.detail.remoteId, event.detail.data]])
-    },
-    [messages],
-  )
-
-  const sendMessage = useCallback(
-    () => {
-      webrtcManager.broadcast('what\'s up friends?')
-    },
-    [webrtcManager],
-  )
-
-  useEffect(() => {
-    if (!webrtcManager) return
-
-    webrtcManager.addEventListener('peerdata', peerdata)
-    return () => {
-      webrtcManager.removeEventListener('peerdata', peerdata)
-    }
-  }, [webrtcManager, peerdata])
-
-  return (
-    <div className="messages-list">
-      <h3>Realm Messages</h3>
-      <pre>
-        { JSON.stringify(messages, null, 2) }
-      </pre>
-      <div>
-        <textarea />
-        <button onClick={sendMessage}>Send</button>
-      </div>
-    </div>
-  )
-}

src/client/components/messenger.tsx

···
+import { RealmConnection } from '#client/realm/connection.js'
+import { useState, useEffect, useCallback } from 'preact/hooks'
+
+export type MessengerProps = {
+  realmConnection: RealmConnection
+}
+
+export const Messenger: preact.FunctionComponent<{ webrtcManager: RealmConnection }> = (props) => {
+  const { webrtcManager } = props
+  const [messages, setMessages] = useState<any[]>([])
+
+  const peerdata = useCallback((event: CustomEvent) => {
+    setMessages([...messages, [event.detail.remoteId, event.detail.data]])
+  }, [messages])
+
+  const sendMessage = useCallback(() => {
+    webrtcManager.broadcast('what\'s up friends?')
+  }, [webrtcManager])
+
+  useEffect(() => {
+    if (!webrtcManager) return
+
+    webrtcManager.addEventListener('peerdata', peerdata as ((event: Event) => void))
+    return () => {
+      webrtcManager.removeEventListener('peerdata', peerdata as ((event: Event) => void))
+    }
+  }, [webrtcManager, peerdata])
+
+  return (
+    <div className="messages-list">
+      <h3>Realm Messages</h3>
+      <pre>
+        { JSON.stringify(messages, null, 2) }
+      </pre>
+      <div>
+        <textarea />
+        <button onClick={sendMessage}>Send</button>
+      </div>
+    </div>
+  )
+}

src/client/components/peer-list.jsx src/client/components/peer-list.tsx

···
-import * as connection_types from '#client/realm/connection.js'
-import * as protocol_types from '#common/protocol.js'
 import { useState, useEffect } from 'preact/hooks'
 
-/**
- * @param {object} props list props
- * @param {connection_types.RealmConnection} props.webrtcManager connection manager
- * @returns {preact.JSX.Element} the peerlist component
- */
-export function PeerList({ webrtcManager }) {
-  const [peers, setPeers] = useState(
-    /** @type {Record<protocol_types.IdentID, connection_types.PeerState>} */ ({}),
-  )
+import { PeerState, RealmConnection } from '#client/realm/connection'
+import { IdentID } from '#common/protocol'
+
+export const PeerList: preact.FunctionComponent<{ webrtcManager: RealmConnection }> = (props) => {
+  const { webrtcManager } = props
+  const [peers, setPeers] = useState<Record<IdentID, PeerState>>({})
 
   useEffect(() => {
     if (!webrtcManager) return
···
           : (
               <ul>
                 {Object.entries(peers).map(([peerId, state]) => (
-                  <li key={peerId} className={`peer-item ${state.state}`}>
+                  <li key={peerId} className={`peer-item`}>
                     <span className="peer-id">{peerId}</span>
                     <ConnectionStatus state={state} />
                   </li>
···
   )
 }
 
-/**
- * @private
- * @param {object} props status props
- * @param {connection_types.PeerState} props.state current state
- * @returns {preact.JSX.Element} the status component
- */
-function ConnectionStatus({ state }) {
+function ConnectionStatus({ state }: { state: PeerState }): preact.JSX.Element {
   const getStatusIcon = () => {
     if (state.connected) return '🟢'
     if (state.destroyed) return '🔴'

src/client/index.jsx src/client/index.tsx

···
+import { render } from 'preact'
+
+import { App } from './page-app'
 import './index.css'
-import { App } from './page-app.jsx'
-import { render } from 'preact'
 
 const root = document.getElementById('app')
 if (root == null)

src/client/page-app.jsx

···
-import { RealmConnectionProvider } from './realm/context.jsx'
-import { WebRTCDemo } from './webrtc-demo.jsx'
-
-/**
- * @returns {preact.JSX.Element} app wrapper component
- */
-export function App() {
-  return (
-    <RealmConnectionProvider url="ws://localhost:3001/stream">
-      <WebRTCDemo />
-    </RealmConnectionProvider>
-  )
-}

src/client/page-app.spec.jsx

···
-/** @jest-environment jest-fixed-jsdom */
-
-import { describe, it, expect } from '@jest/globals'
-
-import { App } from '#client/page-app.jsx'
-import { Fragment } from 'preact/jsx-runtime'
-
-describe('App component', () => {
-  it('creates JSX structure', () => {
-    const component = App()
-    expect(component).toHaveProperty('type')
-    expect(component).toHaveProperty('props')
-  })
-
-  it('returns expected element structure', () => {
-    const component = App()
-
-    // Check the JSX structure without full rendering
-    expect(component.type).toBe(Fragment)
-    expect(component.props.children[0]).toHaveProperty('type', 'h1')
-    expect(component.props.children[0].props.children).toBe('whatever')
-  })
-})
-
-describe('Client-side DOM environment', () => {
-  it('has access to DOM globals', () => {
-    // This test demonstrates that jsdom environment provides DOM APIs
-    expect(typeof document).toBe('object')
-    expect(typeof window).toBe('object')
-    expect(typeof Element).toBe('function')
-  })
-
-  it('can create and manipulate DOM elements', () => {
-    const div = document.createElement('div')
-    div.textContent = 'test content'
-
-    expect(div.tagName).toBe('DIV')
-    expect(div.textContent).toBe('test content')
-  })
-
-  it('can simulate user interactions', () => {
-    const button = document.createElement('button')
-    let clicked = false
-
-    button.addEventListener('click', () => {
-      clicked = true
-    })
-
-    button.click()
-    expect(clicked).toBe(true)
-  })
-})

src/client/page-app.tsx

···
+import { RealmConnectionProvider } from './realm/context'
+import { WebRTCDemo } from './webrtc-demo'
+
+export const App: preact.FunctionComponent = () => {
+  return (
+    <RealmConnectionProvider url="ws://localhost:3001/stream">
+      <WebRTCDemo />
+    </RealmConnectionProvider>
+  )
+}

src/client/realm/connection.js src/client/realm/connection.ts

···
 import { nanoid } from 'nanoid'
 import SimplePeer from 'simple-peer'
 
-import { generateSignableJwt, jwkExport } from '#common/crypto/jwks.js'
-import { normalizeError, normalizeProtocolError, ProtocolError } from '#common/errors.js'
-import { parseJson, realmFromServerMessageSchema, realmRtcPeerWelcomeMessageSchema } from '#common/protocol.js'
-import { sendSocket, streamSocket, streamSocketJson, takeSocketJson } from '#common/socket.js'
+import { generateSignableJwt, jwkExport } from '#common/crypto/jwks'
+import { normalizeError, normalizeProtocolError, ProtocolError } from '#common/errors'
+import { IdentID, RealmBroadcastMessage, realmFromServerMessageSchema, RealmID, RealmRtcPeerWelcomeMessage, realmRtcPeerWelcomeMessageSchema, RealmRtcSignalMessage } from '#common/protocol'
+import { sendSocket, streamSocketJson, takeSocketJson } from '#common/socket'
 
-import * as protocol_types from '#common/protocol.js'
+/** the state of a specific peer */
+export interface PeerState {
 
-/**
- * @typedef {object} PeerState
- * @property {ReturnType<SimplePeer.Instance['address']>} address peer address
- * @property {boolean} connected true if the peer connection is active
- * @property {boolean} destroyed true if the peer connection has been destroyed
- * @property {string} state a simple status string
- */
+  /** true if the peer connection is active */
+  connected: boolean
 
-/**
- * @typedef {object} RealmIdentity
- * @property {protocol_types.RealmID} realmid
- * @property {protocol_types.IdentID} identid
- * @property {CryptoKeyPair} keypair
- */
+  /** true if the peer connection has been destroyed */
+  destroyed: boolean
 
-/**
- * A connection manager
- */
-export class RealmConnection extends EventTarget {
+  /** the peer's address */
+  address: ReturnType<SimplePeer.Instance['address']>
 
-  /** @type {string} */
-  #url
+}
 
-  /** @type {RealmIdentity} */
-  #identity
+export interface RealmIdentity {
+  realmid: RealmID
+  identid: IdentID
+  keypair: CryptoKeyPair
+}
 
-  /** @type {WebSocket} */
-  #socket
+/** A connection manager */
+export class RealmConnection extends EventTarget {
 
-  /** @type {Map<protocol_types.IdentID, SimplePeer.Instance>} */
-  #peers
+  #url: string
+  #identity: RealmIdentity
 
-  /** @type {Map<protocol_types.IdentID, string>} */
-  #nonces
+  #socket: WebSocket
+  #peers: Map<IdentID, SimplePeer.Instance>
+  #nonces: Map<IdentID, string>
 
-  /**
-   * @param {string} url the realm server we're connecting to
-   * @param {RealmIdentity} identity this connection's realm identity
-   */
-  constructor(url, identity) {
+  constructor(url: string, identity: RealmIdentity) {
     super()
 
     this.#url = url
···
     this.#socket.onerror = this.#handleSocketError
   }
 
-  /** @type {WebSocket['onopen']} */
-  #handleSocketOpen = async () => {
+  #handleSocketOpen: WebSocket['onopen'] = async () => {
     if (this.#socket == undefined)
       throw new Error('socket open handler called with no socket?')
 
···
       // the next message should be a welcome message
       // this will throw (authenticated) otherwise
 
-      /** @type {protocol_types.RealmRtcPeerWelcomeMessage} */
-      let welcome
+      let welcome: RealmRtcPeerWelcomeMessage
       try {
         welcome = await takeSocketJson(this.#socket, realmRtcPeerWelcomeMessageSchema)
       }
···
     }
   }
 
-  /** @type {WebSocket['onerror']} */
-  #handleSocketError = async (exc) => {
+  #handleSocketError: WebSocket['onerror'] = async (exc) => {
     this.#dispatchCustomEvent('wserror', { error: normalizeProtocolError(exc) })
     this.destroy()
   }
 
   /** @type {WebSocket['onclose']} */
-  #handleSocketClose = async () => {
+  #handleSocketClose: WebSocket['onclose'] = async () => {
     this.#dispatchCustomEvent('wsclose')
     this.destroy()
   }
···
     this.#nonces.clear()
   }
 
-  /**
-   * dispatch a `CustomEvent`
-   *
-   * @param {string} type the event type (for addEVentListener(type))
-   * @param {object} [detail] the details object to include
-   */
-  #dispatchCustomEvent(type, detail) {
+  #dispatchCustomEvent(type: string, detail?: object) {
     this.dispatchEvent(new CustomEvent(type, { detail }))
   }
 
-  /**
-   * generates and signs a JWT scoped to this identity/realm containing the given payload
-   *
-   * @param {object} payload the payload to embed in the JWT
-   * @returns {Promise<string>} a signed JWT for sending upstream
-   */
-  async #signJwt(payload) {
+  /** generates and signs a JWT scoped to this identity/realm containing the given payload */
+  async #signJwt(payload: object): Promise<string> {
     return await generateSignableJwt({
       aud: this.#identity.realmid,
       iss: this.#identity.identid,
···
     }).sign(this.#identity.keypair.privateKey)
   }
 
-  /**
-   * @private
-   * @param {protocol_types.IdentID} remoteid the identity we're connecting to
-   * @param {boolean} initiator are we the initiator of this connection?
-   * @returns {SimplePeer.Instance} the configured peer for the identid
-   */
-  connectToPeer(remoteid, initiator) {
+  connectToPeer(remoteid: IdentID, initiator: boolean): SimplePeer.Instance {
     let peer = this.#peers.get(remoteid)
     if (peer) {
       console.log(`already connected to ${remoteid}`)
···
     return peer
   }
 
-  /** @param {protocol_types.IdentID} identid the recipient to disconnect from */
-  disconnectPeer(identid) {
+  disconnectPeer(identid: IdentID) {
     const peer = this.#peers.get(identid)
     if (peer) {
       peer.destroy()
···
     }
   }
 
-  /**
-   * @param {protocol_types.IdentID} identid the recipient to send data to
-   * @param {any} data the data to send via peer connection
-   */
-  sendToPeer(identid, data) {
+  sendToPeer(identid: IdentID, data: unknown) {
     const peer = this.#peers.get(identid)
     if (peer && peer.connected) {
       peer.send(JSON.stringify(data))
···
     }
   }
 
-  /**
-   * @param {unknown} data to send along the socket to the realm server
-   */
-  sendToServer(data) {
+  sendToServer(data: unknown) {
     sendSocket(this.#socket, data)
   }
 
-  /** @param {any} data the data to send via peer connection */
-  broadcast(data) {
+  broadcast(data: unknown) {
     const message = JSON.stringify(data)
     for (const [_, peer] of this.#peers) {
       if (peer.connected) {
···
     }
   }
 
-  /** @param {any} data the data to send via server */
-  broadcastViaServer(data) {
-    /** @type {protocol_types.RealmBroadcastMessage} */
-    const resp = {
+  broadcastViaServer(data: unknown) {
+    const resp: RealmBroadcastMessage = {
       msg: 'realm.broadcast',
       payload: data,
       recipients: false,
     }
+
     sendSocket(this.#socket, resp)
   }
 
   /**
    * @returns {Record<protocol_types.IdentID, PeerState>} the current peer state mapping
    */
-  getPeerStates() {
-    /** @type {Record<protocol_types.IdentID, PeerState>} */
-    const states = {}
-
+  getPeerStates(): Record<IdentID, PeerState> {
+    const states: Record<IdentID, PeerState> = {}
     for (const [peerId, peer] of this.#peers) {
       states[peerId] = {
         address: peer.address(),
         connected: peer.connected,
         destroyed: peer.destroyed,
-        state: peer.connected ? 'connected' : 'disconnected',
       }
     }
 
···
  */
 export class RealmConnectionPeer extends SimplePeer {
 
-  /** @type {RealmConnection} */
-  #connection
+  #connection: RealmConnection
 
-  /** @type {boolean} */
-  initiator
-
-  /** @type {protocol_types.IdentID} */
-  localid
-
-  /** @type {protocol_types.IdentID} */
-  remoteid
-
-  /** @type {string} */
-  nonce
+  initiator: boolean
+  localid: IdentID
+  remoteid: IdentID
+  nonce: string
 
-  /**
-   * @param {RealmConnection} connection the connection that owns this peer
-   * @param {string} nonce a uniquely identifying string for this peer
-   * @param {protocol_types.IdentID} localid the local identity
-   * @param {protocol_types.IdentID} remoteid the remote identity
-   * @param {boolean} initiator whether we're initiating the connection
-   */
-  constructor(connection, nonce, localid, remoteid, initiator) {
+  constructor(connection: RealmConnection, nonce: string, localid: IdentID, remoteid: IdentID, initiator: boolean) {
     super({
       initiator,
       config: {
···
     this.on('data', this.#handlePeerData)
   }
 
-  /** @type {function(SimplePeer.SignalData): void} */
-  #handlePeerSignal = (e) => {
+  #handlePeerSignal = (e: SimplePeer.SignalData) => {
     this.#connection.sendToServer(
-      /** @type {protocol_types.RealmRtcSignalMessage} */
-      ({
+      {
         msg: 'realm.rtc.signal',
         initiator: this.initiator,
         sender: this.localid,
         recipient: this.remoteid,
         payload: JSON.stringify(e),
-      }),
+      } satisfies RealmRtcSignalMessage,
     )
   }
 
-  /** @type {function(string): void} */
-  #handlePeerData = (chunk) => {
+  #handlePeerData = (chunk: string) => {
     try {
       const parsed = JSON.parse(chunk)
       switch (parsed.type) {

src/client/realm/context.jsx

···
-import { createContext } from 'preact'
-import * as preact_types from 'preact'
-import * as connection_types from '#client/realm/connection.js'
-
-import { RealmConnection } from '#client/realm/connection.js'
-import { useCallback, useEffect, useState } from 'preact/hooks'
-
-/**
- * @typedef {object} RealmConnectionContext
- * @property {RealmConnection | null} realm the realm server we're connected to
- * @property {connection_types.RealmIdentity | null} identity the realm identity we're connected as
- * @property {function(connection_types.RealmIdentity): void} setIdentity
- * a callback to set the current identity
- */
-
-export const RealmConnectionContext
-  = createContext(/** @type {RealmConnectionContext | null} */ (null))
-
-/**
- * @typedef {object} RealmConnectionProviderProps
- * @property {string} url the realm server to connect to
- * @property {preact_types.ComponentChildren} children the children to render
- */
-
-/**
- * @type {preact.FunctionComponent<RealmConnectionProviderProps>}
- */
-export const RealmConnectionProvider = (props) => {
-  const [identity$, setIdentity$]
-    = useState(/** @type {connection_types.RealmIdentity | null} */ (null))
-
-  const [connection$, setConnection$]
-    = useState(/** @type {RealmConnection | null} */ (null))
-
-  const connect = useCallback(
-    () => {
-      if (connection$) return
-      if (!identity$) return
-
-      const connection = new RealmConnection(props.url, identity$)
-      setConnection$(connection)
-    },
-    [connection$, identity$, props.url],
-  )
-
-  const disconnect = useCallback(
-    () => {
-      connection$?.destroy()
-    },
-    [connection$],
-  )
-
-  useEffect(
-    () => {
-      console.log('use effect in provider', identity$)
-      // connect on mount, or identity change
-      if (identity$) connect()
-
-      // disconnect on unsubscribe
-      return disconnect
-    },
-    [connect, disconnect, identity$],
-  )
-
-  return (
-    <RealmConnectionContext.Provider
-      children={props.children}
-      value={{
-        realm: connection$,
-        identity: identity$,
-        setIdentity: setIdentity$,
-      }}
-    />
-  )
-}

src/client/realm/context.tsx

···
+import { createContext } from 'preact'
+import { useCallback, useEffect, useState } from 'preact/hooks'
+
+import { RealmConnection, RealmIdentity } from '#client/realm/connection.js'
+
+interface RealmConnectionContext {
+  realm?: RealmConnection
+  identity?: RealmIdentity
+  setIdentity: (ident: RealmIdentity) => void
+}
+
+export const RealmConnectionContext = createContext<RealmConnectionContext | null>(null)
+
+export const RealmConnectionProvider: preact.FunctionComponent<{
+  url: string
+  children: preact.ComponentChildren
+}> = (props) => {
+
+  const [identity$, setIdentity$]     = useState<RealmIdentity>()
+  const [connection$, setConnection$] = useState<RealmConnection>()
+
+  const connect = useCallback(() => {
+    if (connection$) return
+    if (!identity$) return
+
+    setConnection$(
+      new RealmConnection(props.url, identity$)
+    )
+  }, [connection$, identity$, props.url])
+
+  const disconnect = useCallback(() => {
+    connection$?.destroy()
+  }, [connection$])
+
+  useEffect(() => {
+    console.log('use effect in provider', identity$)
+    // connect on mount, or identity change
+    if (identity$) connect()
+
+    // disconnect on unsubscribe
+    return disconnect
+  }, [connect, disconnect, identity$])
+
+  return (
+    <RealmConnectionContext.Provider
+      children={props.children}
+      value={{
+        realm: connection$,
+        identity: identity$,
+        setIdentity: setIdentity$,
+      }}
+    />
+  )
+}

src/client/webrtc-demo.jsx src/client/webrtc-demo.tsx

···
-// @ts-nocheck
-
 import { useEffect, useContext, useCallback } from 'preact/hooks'
 
-import { RealmConnectionContext } from '#client/realm/context.jsx'
-import { PeerList } from '#client/components/peer-list.jsx'
+import { RealmConnectionContext } from '#client/realm/context'
+import { PeerList } from '#client/components/peer-list'
 
-import * as protocol from '#common/protocol.js'
-import { generateSigningJwkPair } from '#common/crypto/jwks.js'
+import * as protocol from '#common/protocol'
+import { generateSigningJwkPair } from '#common/crypto/jwks'
 import { Messenger } from './components/messenger'
+import { Callback } from '#common/types.js'
 
-/**
- * @private
- * @param {EventTarget} target event target to attach
- * @param {string} name the name of the event to listen to
- * @param {function(): void} listener the listener to add
- * @returns {function(): void} the listener, for removing later
- */
-function attachEventListener(target, name, listener) {
+function attachEventListener<CB extends Callback>(target: EventTarget, name: string, listener: CB): CB {
   target.addEventListener(name, listener)
   return listener
 }
 
-/**
- * @private
- * @returns {preact.JSX.Element}
- */
-export function WebRTCDemo() {
+export const WebRTCDemo: preact.FunctionComponent = () => {
   const context = useContext(RealmConnectionContext)
   if (!context)
     throw new Error('expected to be called inside realm connection context!')

src/cmd/register-ident.js src/cmd/register-ident.ts

···
 #!/usr/bin/env node
 
-import { generateSignableJwt, generateSigningJwkPair, jwkExport } from '#common/crypto/jwks.js'
-import { IdentBrand, RealmBrand } from '#common/protocol.js'
+import { generateSignableJwt, generateSigningJwkPair, jwkExport } from '#common/crypto/jwks'
+import { IdentBrand, RealmBrand } from '#common/protocol'
 
-/**
- * @private
- * @param {string} realm the realm to register against
- */
-async function generateRegistrationJWT(realm) {
+async function generateRegistrationJWT(realm?: string) {
   const keypair = await generateSigningJwkPair()
   const realmid = realm ?? RealmBrand.generate()
   const identid = IdentBrand.generate()

src/cmd/server.js src/cmd/server.ts

···
 import { fileURLToPath } from 'url'
 import { parseArgs } from 'util'
 
-import { buildServer } from '#server/index.js'
+import { buildServer } from '#server/index'
 
 const __filename = fileURLToPath(import.meta.url)
 const __dirname = dirname(__filename)
···
 
 buildServer(root).listen(port, host, () => {
   console.log(`
-  skypod ⚡️ http://${host}:${port}
+    skypod ⚡️ http://${host}:${port}
   `)
 })

src/common/async/aborts.js

···
-/**
- * @typedef {object} TimeoutSignal
- * @property {AbortSignal} signal the ticking signal
- * @property {VoidFunction} cancel a cleanup function, to cancel the timer
- */
-
-import * as common_types from '#common/types.js'
-
-/**
- * returns a new abort signal which will abort after some timeout, unless cancelled.
- * better than AbortSignal.timeout because it consistently aborts with a timeout error
- *
- * @param {number} ms - timeout in milliseconds
- * @returns {TimeoutSignal} a cancellable timeout abort signal.
- */
-export function timeoutSignal(ms) {
-  const controller = new AbortController()
-
-  const timeout = setTimeout(() => {
-    controller.abort(
-      new DOMException('Operation timed out', 'TimeoutError'),
-    )
-  }, ms)
-
-  const cancel = () => {
-    clearTimeout(timeout)
-    controller.signal.removeEventListener('abort', cancel)
-  }
-
-  controller.signal.addEventListener('abort', cancel)
-  return { signal: controller.signal, cancel }
-}
-
-/**
- * @param {Array<AbortSignal | undefined>} signals the list of signals to combine
- * @returns {AbortSignal} a combined signal, which will abort when any given signal does
- */
-export function combineSignals(...signals) {
-  /** @type {Array<common_types.VoidCallback>} */
-  const cleanups = []
-  const controller = new AbortController()
-
-  for (const signal of signals) {
-    if (signal == undefined) continue
-
-    if (signal.aborted) {
-      controller.abort(signal.reason)
-      return controller.signal
-    }
-
-    const handler = () => {
-      if (!controller.signal.aborted) {
-        controller.abort(signal.reason)
-      }
-    }
-
-    signal.addEventListener('abort', handler)
-    cleanups.push(() => signal.removeEventListener('abort', handler))
-  }
-
-  controller.signal.addEventListener('abort', () => {
-    cleanups.forEach(cb => cb())
-  })
-
-  return controller.signal
-}

src/common/async/aborts.ts

···
+export interface TimeoutSignal {
+  signal: AbortSignal
+  cancel: () => void
+}
+
+/**
+ * returns a new abort signal which will abort after some timeout, unless cancelled.
+ * better than AbortSignal.timeout because it consistently aborts with a timeout error
+ */
+export function timeoutSignal(ms: number): TimeoutSignal {
+  const controller = new AbortController()
+
+  const timeout = setTimeout(() => {
+    controller.abort(new DOMException('Operation timed out', 'TimeoutError'))
+  }, ms)
+
+  const cancel = () => {
+    clearTimeout(timeout)
+    controller.signal.removeEventListener('abort', cancel)
+  }
+
+  controller.signal.addEventListener('abort', cancel)
+  return { signal: controller.signal, cancel }
+}
+
+/**
+ * @param signals the list of signals to combine
+ * @returns a combined signal, which will abort when any given signal does
+ */
+export function combineSignals(...signals: Array<AbortSignal | undefined>): AbortSignal {
+  const cleanups: Array<() => void> = []
+  const controller = new AbortController()
+
+  for (const signal of signals) {
+    if (signal == undefined) continue
+
+    if (signal.aborted) {
+      controller.abort(signal.reason)
+      return controller.signal
+    }
+
+    const handler = () => {
+      if (!controller.signal.aborted) {
+        controller.abort(signal.reason)
+      }
+    }
+
+    signal.addEventListener('abort', handler)
+    cleanups.push(() => signal.removeEventListener('abort', handler))
+  }
+
+  controller.signal.addEventListener('abort', () => {
+    cleanups.forEach(cb => cb())
+  })
+
+  return controller.signal
+}

src/common/async/blocking-atom.js

···
-/** @module common/async */
-
-import { Semaphore } from './semaphore.js'
-
-/**
- * simple blocking atom, for waiting for a value.
- * cribbed mostly from {@link https://github.com/ComFreek/async-playground}
- *
- * @template T - the type we're holding
- */
-export class BlockingAtom {
-
-  /** @type {T | undefined} */
-  #item
-
-  /** @type {Semaphore} */
-  #sema
-
-  constructor() {
-    this.#sema = new Semaphore()
-    this.#item = undefined
-  }
-
-  /**
-   * puts an item into the atom and unblocks an awaiter.
-   *
-   * @param {T} item the item to put into the atom
-   */
-  set(item) {
-    this.#item = item
-    this.#sema.free()
-  }
-
-  /**
-   * tries to get the item from the atom, and blocks until available.
-   *
-   * @example
-   *   if (await atom.take())
-   *     console.log('got it!')
-   *
-   * @param {AbortSignal | undefined} signal - an abort signal to cancel the await
-   * @returns {Promise<T | undefined>} a promise for the item, or undefined if something aborted.
-   */
-  async get(signal) {
-    if (await this.#sema.take(signal)) {
-      return this.#item
-    }
-
-    signal?.throwIfAborted()
-  }
-
-}

src/common/async/blocking-atom.ts

···
+/** @module common/async */
+
+import { Semaphore } from './semaphore.js'
+
+/**
+ * simple blocking atom, for waiting for a value.
+ * cribbed mostly from {@link https://github.com/ComFreek/async-playground}
+ *
+ * @template T - the type we're holding
+ */
+export class BlockingAtom<T> {
+
+  #item: T | undefined
+  #sema: Semaphore
+
+  constructor() {
+    this.#sema = new Semaphore()
+    this.#item = undefined
+  }
+
+  /** puts an item into the atom and unblocks an awaiter. */
+  set(item: T) {
+    this.#item = item
+    this.#sema.free()
+  }
+
+  /**
+   * tries to get the item from the atom, and blocks until available.
+   *
+   * @example
+   *   if (await atom.take())
+   *     console.log('got it!')
+   *
+   * @param signal - an abort signal to cancel the await
+   * @returns a promise for the item, or undefined if something aborted.
+   */
+  async get(signal: AbortSignal | undefined): Promise<T | undefined> {
+    if (await this.#sema.take(signal)) {
+      return this.#item
+    }
+
+    signal?.throwIfAborted()
+  }
+
+}

src/common/async/blocking-queue.js src/common/async/blocking-queue.ts

···
 /**
  * simple blocking queue, for turning streams into async pulls.
  * cribbed mostly from {@link https://github.com/ComFreek/async-playground}
- *
- * @template T
  */
-export class BlockingQueue {
+export class BlockingQueue<T> {
 
-  /** @type {Semaphore} */
-  #sema
-
-  /** @type {T[]} */
-  #items
-
-  /** @type {number | undefined} */
-  #maxsize
+  #sema: Semaphore
+  #maxsize?: number
+  #items: T[]
 
   constructor(maxsize = 1000) {
     this.#sema = new Semaphore()
-    this.#items = []
     this.#maxsize = maxsize ? maxsize : undefined
+    this.#items = []
   }
 
   /** @returns {number} how deep is the queue? */
-  get depth() {
+  get depth(): number {
     return this.#items.length
   }
 
-  /**
-   * place one or more items on the queue, to be picked up by awaiters.
-   *
-   * @param {...T} elements the items to place on the queue.
-   */
-  prequeue(...elements) {
+  /** place one or more items on the queue, to be picked up by awaiters. */
+  prequeue(...elements: T[]) {
     for (const el of elements.reverse()) {
       if (this.#maxsize && this.#items.length >= this.#maxsize) {
         throw Error('out of room')
···
     }
   }
 
-  /**
-   * place one or more items on the queue, to be picked up by awaiters.
-   *
-   * @param {...T} elements the items to place on the queue.
-   */
-  enqueue(...elements) {
+  /** place one or more items on the queue, to be picked up by awaiters. */
+  enqueue(...elements: T[]) {
     for (const el of elements) {
       if (this.#maxsize && this.#items.length >= this.#maxsize) {
         throw Error('out of room')
···
   /**
    * block while waiting for an item off the queue.
    *
-   * @param {AbortSignal} [signal] a signal to use for aborting the block.
-   * @returns {Promise<T>} the item off the queue; rejects if aborted.
+   * @param [signal] a signal to use for aborting the block.
+   * @returns the item off the queue; rejects if aborted.
    */
-  async dequeue(signal) {
+  async dequeue(signal?: AbortSignal): Promise<T> {
     if (await this.#sema.take(signal)) {
       return this.#poll()
     }

src/common/async/semaphore.js src/common/async/semaphore.ts

···
  */
 export class Semaphore {
 
-  /** @type { number } */
-  #counter = 0
-
-  /** @type {Array<function(boolean): void>} */
-  #resolvers = []
+  #counter: number = 0
+  #resolvers: Array<((taken: boolean) => void)> = []
 
   constructor(count = 0) {
     this.#counter = count
···
    * try to take from the semaphore, reducing it's count
    * if the semaphore is empty, blocks until available, or the given signal aborts.
    *
-   * @param {AbortSignal | undefined} signal a signal to use to abort the block
-   * @returns {Promise<boolean>} true if the semaphore was successfully taken, false if aborted.
+   * @param signal a signal to use to abort the block
+   * @returns true if the semaphore was successfully taken, false if aborted.
    */
-  take(signal) {
+  take(signal?: AbortSignal): Promise<boolean> {
     return new Promise((resolve) => {
       if (signal?.aborted) return resolve(false)
 
···
     })
   }
 
-  /**
-   * try to take from the semaphore, reducing it's count, *without blocking*.
-   *
-   * @returns {boolean} true if the semaphore was taken, false otherwise.
-   */
-  poll() {
+  /** try to take from the semaphore, reducing it's count, *without blocking*. */
+  poll(): boolean {
     if (this.#counter <= 0) return false
 
     this.#counter--

src/common/async/sleep.js

···
-/** @module common/async */
-
-/**
- * @param {number} ms the number of ms to sleep
- * @param {AbortSignal} [signal] an aptional abort signal, to cancel the sleep
- * @returns {Promise<void>}
- * a promise that resolves after given amount of time, and is interruptable with an abort signal.
- */
-export function sleep(ms, signal) {
-  signal?.throwIfAborted()
-
-  const { resolve, reject, promise } = Promise.withResolvers()
-  const timeout = setTimeout(resolve, ms)
-
-  if (signal) {
-    const abortHandler = () => {
-      clearTimeout(timeout)
-      reject(signal.reason)
-    }
-
-    signal.addEventListener('abort', abortHandler)
-    promise.finally(() => {
-      signal.removeEventListener('abort', abortHandler)
-    })
-  }
-
-  return promise
-}

src/common/async/sleep.ts

···
+/** @module common/async */
+
+/**
+ * @param ms the number of ms to sleep
+ * @param [signal] an aptional abort signal, to cancel the sleep
+ * @returns a promise that resolves after given amount of time, and is interruptable with an abort signal.
+ */
+export function sleep(ms: number, signal?: AbortSignal): Promise<void> {
+  signal?.throwIfAborted()
+
+  const { resolve, reject, promise } = Promise.withResolvers<void>()
+  const timeout = setTimeout(resolve, ms)
+
+  if (signal) {
+    const abortHandler = () => {
+      clearTimeout(timeout)
+      reject(signal.reason)
+    }
+
+    signal.addEventListener('abort', abortHandler)
+    promise.finally(() => {
+      signal.removeEventListener('abort', abortHandler)
+    })
+  }
+
+  return promise
+}

src/common/breaker.js src/common/breaker.ts

···
 /** @module common/async */
 
-import * as common_types from '#common/types.js'
+import { Callback } from "#common/types"
 
 /**
  * A Breaker, which allows creating wrapped functions which will only be executed before
···
  */
 export class Breaker {
 
-  /** @type {undefined | common_types.VoidCallback} */
-  #onTripped
-
-  /** @type {boolean} */
-  #tripped
+  #tripped: boolean
+  #onTripped?: () => void
 
   /**
-   * @param {common_types.VoidCallback} [onTripped]
+   * @param [onTripped]
    * an optional callback, called when the breaker is tripped, /before/ any wrapped functions.
    */
-  constructor(onTripped) {
+  constructor(onTripped?: () => void) {
     this.#tripped = false
     this.#onTripped = onTripped
   }
 
-  /** @returns {boolean} true if the breaker has already tripped */
-  tripped() {
+  /** @returns true if the breaker has already tripped */
+  tripped(): boolean {
     return this.#tripped
   }
 
···
    * wrap the given callback in a function that will trip the breaker before it's called.
    * any subsequent calls to the wrapped function will be no-ops.
    *
-   * @param {common_types.Callback} fn the function to be wrapped in the breaker
-   * @returns {common_types.Callback} a wrapped function, controlled by the breaker
+   * @param fn the function to be wrapped in the breaker
+   * @returns a wrapped function, controlled by the breaker
    */
-  tripThen(fn) {
-    return (...args) => {
+  tripThen<CB extends Callback>(fn: CB): CB {
+    return ((...args: Parameters<CB>): void => {
       if (!this.#tripped) {
         this.#tripped = true
 
···
         this.#onTripped?.()
         fn(...args)
       }
-    }
+    }) as CB
   }
 
   /**
···
    * @param {common_types.Callback} fn the function to be wrapped in the breaker
    * @returns {common_types.Callback} a wrapped function, controlled by the breaker
    */
-  untilTripped(fn) {
-    return (...args) => {
+  untilTripped<CB extends Callback>(fn: CB): CB {
+    return ((...args: Parameters<CB>): void => {
       if (!this.#tripped) {
         // TODO: if these throw, what to do?
         fn(...args)
       }
-    }
+    }) as CB
   }
 
 }

src/common/crypto/cipher.js src/common/crypto/cipher.ts

···
 const encrAlgo = { name: 'AES-GCM', length: 256 }
 const deriveAlgo = { name: 'PBKDF2', hash: 'SHA-256' }
 
-/**
- * @private
- * @param {string} [s] a possibly undefined or null input string
- * @returns {string} either the input or a medium-resistent random string
- */
-function orRandom(s) {
+function orRandom(s: string): string {
   return s ?? nanoid(10)
 }
 
-/**
- * @private
- * @param {string|Uint8Array} s a string or uint8array
- * @returns {Uint8Array} either the input or a medium-resistent random string
- */
-function asUint8Array(s) {
+function asUint8Array(s: string | Uint8Array): Uint8Array {
   if (s instanceof Uint8Array) {
     return s
   }
-
-  if (typeof s === 'string') {
+  else if (typeof s === 'string') {
     return new TextEncoder().encode(s)
   }
 
···
  *
  * @private
  *
- * @param {string} passwordStr a password for derivation
- * @param {string} saltStr a salt for derivation
- * @param {string} nonceStr a nonce for derivation
- * @param {number} [iterations] number of iterations for pbkdf
- * @returns {Promise<CryptoKey>} the derived crypto key
+ * @param passwordStr a password for derivation
+ * @param saltStr a salt for derivation
+ * @param nonceStr a nonce for derivation
+ * @param [iterations] number of iterations for pbkdf
+ * @returns the derived crypto key
  */
-async function deriveKey(passwordStr, saltStr, nonceStr, iterations = 100000) {
+async function deriveKey(passwordStr: string, saltStr: string, nonceStr: string, iterations: number = 100000): Promise<CryptoKey> {
   const encoder = new TextEncoder()
 
   const password = encoder.encode(`${passwordStr}-pass-cryptosystem`)
···
    * any missing parameter (password/salt/nonce) is replaced with a random value,
    * but if a stable password/salt/nonce is given, the derived keys will be stable.
    *
-   * @param {string} [passwordStr] a password for derivation
-   * @param {string} [saltStr] a salt for derivation
-   * @param {string} [nonceStr] a nonce for derivation
-   * @returns {Promise<Cipher>} the derived {@link Cipher}
+   * @param [passwordStr] a password for derivation
+   * @param [saltStr] a salt for derivation
+   * @param [nonceStr] a nonce for derivation
+   * @returns the derived {@link Cipher}
    */
-  static async derive(passwordStr, saltStr, nonceStr) {
+  static async derive(passwordStr: string, saltStr: string, nonceStr: string): Promise<Cipher> {
     const cryptokey = await deriveKey(orRandom(passwordStr), orRandom(saltStr), orRandom(nonceStr))
     return new this(cryptokey)
   }
 
-  /** @type {CryptoKey} */
-  #cryptokey
+  #cryptokey: CryptoKey
 
   /**
    * import a cipher from an aleady existing {@link CryptoKey}.
    * does _not_ ensure that the imported key will work with our preferred encryption
    *
-   * @param {CryptoKey} cryptokey the key to import into a Cipher
+   * @param cryptokey the key to import into a Cipher
    */
-  constructor(cryptokey) {
+  constructor(cryptokey: CryptoKey) {
     this.#cryptokey = cryptokey
   }
 
   /**
-   * @param {(string | Uint8Array)} data the data to encrypte
-   * @returns {Promise<string>} a url-safe base64 encoded encrypted string.
+   * @param data the data to encrypte
+   * @returns a url-safe base64 encoded encrypted string.
    */
-  async encrypt(data) {
+  async encrypt(data: (string | Uint8Array)): Promise<string> {
     const iv = crypto.getRandomValues(new Uint8Array(12))
     const encoded = asUint8Array(data)
     const encrypted = await crypto.subtle.encrypt({ ...encrAlgo, iv }, this.#cryptokey, encoded)
···
   }
 
   /**
-   * @param {string} encryptedData a base64 encoded string, previously encrypted with this cipher.
-   * @returns {Promise<string>} the decrypted output, decoded into utf-8 text.
+   * @param encryptedData a base64 encoded string, previously encrypted with this cipher.
+   * @returns the decrypted output, decoded into utf-8 text.
    */
-  async decryptText(encryptedData) {
+  async decryptText(encryptedData: string): Promise<string> {
     const plainbytes = await this.decryptBytes(encryptedData)
     return new TextDecoder().decode(plainbytes)
   }
 
   /**
-   * @param {string} encryptedData a base64 encoded string, previously encrypted with this cipher.
-   * @returns {Promise<ArrayBuffer>} the decrypted output, as an array buffer of bytes.
+   * @param encryptedData a base64 encoded string, previously encrypted with this cipher.
+   * @returns the decrypted output, as an array buffer of bytes.
    */
-  async decryptBytes(encryptedData) {
+  async decryptBytes(encryptedData: string): Promise<ArrayBuffer> {
     const combined = base64url.decode(encryptedData)
 
     // Extract IV and encrypted data (which includes auth tag)

src/common/crypto/errors.js

···
-import { BaseError } from '#common/errors.js'
-import * as errors_types from '#common/errors.js'
-
-/** Common base class for errors in the crypto module */
-export class CryptoError extends BaseError {
-}
-
-/** Thrown when failing to verify a JWT signature */
-export class JWTBadSignatureError extends CryptoError {
-
-  /**
-   * @param {errors_types.BaseErrorOpts} [options] options to pass upstream
-   */
-  constructor(options) {
-    super('could not verify token signature', options)
-  }
-
-}

src/common/crypto/errors.ts

···
+import { BaseError, BaseErrorOpts } from '#common/errors.js'
+
+/** Common base class for errors in the crypto module */
+export class CryptoError extends BaseError {}
+
+/** Thrown when failing to verify a JWT signature */
+export class JWTBadSignatureError extends CryptoError {
+
+  constructor(options?: BaseErrorOpts) {
+    super('could not verify token signature', options)
+  }
+
+}

src/common/crypto/jwks.js src/common/crypto/jwks.ts

···
  *
  * @see https://www.rfc-editor.org/rfc/rfc7517
  * @see https://github.com/panva/jose/blob/main/src/types.d.ts#L2
- * @type {z.ZodType<JWK>}
  */
-export const jwkSchema = z.union([
+export const jwkSchema: z.ZodType<jose.JWK> = z.union([
   jwkEcPublicSchema,
   jwkEcPrivateSchema,
 ])
 
 /**
  * zod transform from JWK to CryptoKey
- *
- * @type {z.ZodTransform<CryptoKey, JWK>}
  */
-export const jwkImport = z.transform(async (val, ctx) => {
+export const jwkImport: z.ZodTransform<CryptoKey, jose.JWK> = z.transform(async (val, ctx) => {
   try {
     if (typeof val === 'object' && val !== null) {
       const key = await jose.importJWK(val, joseSignAlgo.name)
···
   return z.NEVER
 })
 
-/**
- * zod transform from exportable CryptoKey to JWK
- *
- * @type {z.ZodTransform<JWK, CryptoKey>}
- */
-export const jwkExport = z.transform(async (val, ctx) => {
+/** zod transform from exportable CryptoKey to JWK */
+export const jwkExport: z.ZodTransform<jose.JWK, CryptoKey> = z.transform(async (val, ctx) => {
   try {
     if (val.extractable) {
       return await jose.exportJWK(val)
···
 })
 
 /**
- * @returns {Promise<CryptoKeyPair>} a newly generated, signing compatible keypair
+ * @returns a newly generated, signing compatible keypair
  */
-export async function generateSigningJwkPair() {
+export async function generateSigningJwkPair(): Promise<CryptoKeyPair> {
   const pair = await crypto.subtle.generateKey(subtleSignAlgo, true, ['sign', 'verify'])
   if (!('publicKey' in pair))
     throw new CryptoError('keypair returned a single key!?')
···
 }
 
 /**
- * @param {jose.JWTPayload} payload the payload to sign
- * @returns {jose.SignJWT} a properly configured jwt signer, with the payload provided
+ * @param payload the payload to sign
+ * @returns a properly configured jwt signer, with the payload provided
  */
-export function generateSignableJwt(payload) {
+export function generateSignableJwt(payload: jose.JWTPayload): jose.SignJWT {
   return new jose.SignJWT(payload)
     .setProtectedHeader({ alg: joseSignAlgo.name })
 }

src/common/crypto/jwts.js

···
-/** @module common/crypto */
-
-import * as jose from 'jose'
-import { z } from 'zod/v4'
-import { JWTBadSignatureError } from '#common/crypto/errors.js'
-import { normalizeError } from '#common/errors.js'
-
-const signAlgo = { name: 'ES256' }
-
-/**
- * @typedef {object} JWTToken
- * @property {string} token the still-encoded JWT, for later verification
- * @property {jose.JWTPayload} claims the decoded JWT payload, for later verification
- */
-
-/**
- * @template T
- * @typedef {object} JWTTokenPayload
- * @property {string} token the still-encoded JWT, for later verification
- * @property {jose.JWTPayload} claims the decoded JWT payload, for later verification
- * @property {T} payload the validate payload type, extracted from a payloadkey
- */
-
-/**
- * schema describing a decoded JWT.
- * **important** - this does no claims validation, only decoding from string to JWT!
- *
- * @type {z.ZodType<JWTToken, string>}
- */
-export const jwtSchema = z.jwt({ abort: true }).transform((token, ctx) => {
-  try {
-    const claims = jose.decodeJwt(token)
-    return { claims, token }
-  }
-  catch (e) {
-    ctx.issues.push({
-      code: 'custom',
-      message: `error while decoding token: ${e}`,
-      input: token,
-    })
-
-    return z.NEVER
-  }
-})
-
-/**
- * schema describing a verified payload in a JWT.
- * **important** - this does no claims validation, only decoding from string to JWT!
- *
- * @template T
- * @param {z.ZodType<T>} schema the schema to extract from the payload
- * @returns {z.ZodType<JWTTokenPayload<T>>} transformer
- */
-export const jwtPayload = (schema) => {
-  const parser = z.looseObject({ payload: schema })
-
-  return jwtSchema.transform(async (payload, ctx) => {
-    const result = await parser.safeParseAsync(payload.claims)
-    if (result.success)
-      return { ...payload, payload: result.data.payload }
-
-    result.error.issues.forEach((iss) => {
-      ctx.issues.push(iss)
-    })
-
-    return z.NEVER
-  })
-}
-
-/** @typedef {Partial<Omit<jose.JWTVerifyOptions, 'algorithms'>>} VerifyOpts */
-
-/**
- * @param {string} jwt the (still encoded) token to verify
- * @param {CryptoKey} pubkey the key with which to verify the token
- * @param {VerifyOpts} [options] the key with which to verify the token
- * @returns {Promise<jose.JWTPayload>} a verified payload
- * @throws {JWTBadSignatureError} if the signature is not valid
- */
-export async function verifyJwtToken(jwt, pubkey, options = {}) {
-  try {
-    const result = await jose.jwtVerify(jwt, pubkey, {
-      algorithms: [signAlgo.name],
-      ...options,
-    })
-
-    return result.payload
-  }
-  catch (exc) {
-    const err = normalizeError(exc)
-    throw new JWTBadSignatureError({ cause: err })
-  }
-}
-
-/**
- * generate a fingerprint for the given crypto key
- *
- * @param {CryptoKey} key the key to fingerprint
- * @returns {Promise<string>} the sha256 fingerprint of the key
- */
-export async function fingerprintKey(key) {
-  return await jose.calculateJwkThumbprint(key, 'sha256')
-}

src/common/crypto/jwts.ts

···
+/** @module common/crypto */
+
+import * as jose from 'jose'
+import { z } from 'zod/v4'
+import { JWTBadSignatureError } from '#common/crypto/errors'
+import { normalizeError } from '#common/errors'
+
+const signAlgo = { name: 'ES256' }
+
+interface JWTToken {
+  token: string
+  claims: jose.JWTPayload
+}
+
+interface JWTTokenPayload<T> {
+  token: string
+  claims: jose.JWTPayload
+  payload: T
+}
+
+/**
+ * schema describing a decoded JWT.
+ * **important** - this does no claims validation, only decoding from string to JWT!
+ */
+export const jwtSchema: z.ZodType<JWTToken, string> = z.jwt({ abort: true }).transform((token, ctx) => {
+  try {
+    const claims = jose.decodeJwt(token)
+    return { claims, token }
+  }
+  catch (e) {
+    ctx.issues.push({
+      code: 'custom',
+      message: `error while decoding token: ${e}`,
+      input: token,
+    })
+
+    return z.NEVER
+  }
+})
+
+/**
+ * schema describing a verified payload in a JWT.
+ * **important** - this does no claims validation, only decoding from string to JWT!
+ */
+export const jwtPayload = <T>(schema: z.ZodType<T>): z.ZodType<JWTTokenPayload<T>> => {
+  const parser = z.looseObject({ payload: schema })
+
+  return jwtSchema.transform(async (payload, ctx) => {
+    const result = await parser.safeParseAsync(payload.claims)
+    if (result.success)
+      return { ...payload, payload: result.data.payload }
+
+    result.error.issues.forEach((iss) => {
+      ctx.issues.push(iss)
+    })
+
+    return z.NEVER
+  })
+}
+
+type VerifyOpts = Partial<Omit<jose.JWTVerifyOptions, 'algorithms'>>
+
+/**
+ * @param jwt the (still encoded) token to verify
+ * @param pubkey the key with which to verify the token
+ * @param [options] the key with which to verify the token
+ * @returns a verified payload
+ * @throws if the signature is not valid
+ */
+export async function verifyJwtToken(jwt: string, pubkey: CryptoKey, options: VerifyOpts = {}): Promise<jose.JWTPayload> {
+  try {
+    const result = await jose.jwtVerify(jwt, pubkey, {
+      algorithms: [signAlgo.name],
+      ...options,
+    })
+
+    return result.payload
+  }
+  catch (exc) {
+    const err = normalizeError(exc)
+    throw new JWTBadSignatureError({ cause: err })
+  }
+}
+
+/**
+ * generate a fingerprint for the given crypto key
+ *
+ * @param key the key to fingerprint
+ * @returns the sha256 fingerprint of the key
+ */
+export async function fingerprintKey(key: CryptoKey): Promise<string> {
+  return await jose.calculateJwkThumbprint(key, 'sha256')
+}

src/common/errors.js

···
-/** @module common */
-
-import { prettifyError, ZodError } from 'zod/v4'
-
-/**
- * @private
- * @type {Record<number, string>}
- */
-const StatusCodes = {
-  400: 'Bad Request',
-  401: 'Unauthorized',
-  403: 'Forbidden',
-  404: 'Not Found',
-  408: 'Request Timeout',
-  409: 'Conflict',
-  429: 'Too Many Requests',
-  499: 'Client Closed Request',
-  500: 'Internal Server Error',
-}
-
-/**
- * @typedef {object} BaseErrorOpts
- * @property {Error | undefined} cause the cause of the error.
- */
-
-/**
- * Common base class for Skypod Errors
- * only difference is that we explicitly type cause to be Error
- *
- * @augments Error
- * @property {Error | undefined} cause the cause of the error.
- */
-// cause is called out in order to get a known type
-export class BaseError extends Error {
-
-  /**
-   * @param {string} message a "details" message representing this error
-   * @param {BaseErrorOpts} [options] a previous error we're wrapping
-   */
-  constructor(message, options) {
-    super(message, options)
-
-    if (options?.cause)
-      this.cause = normalizeError(options.cause)
-  }
-
-}
-
-/**
- * Common base class for Websocket Errors
- *
- * @augments BaseError
- */
-export class ProtocolError extends BaseError {
-
-  /**
-   * @param {string} message a "details" message representing this error
-   * @param {number} status the HTTP status code representing this error
-   * @param {BaseErrorOpts} [options] a previous error we're wrapping
-   */
-  constructor(message, status, options) {
-    const statusText = StatusCodes[status] || 'Unknown'
-    super(`${status} ${statusText}: ${message}`, options)
-
-    this.name = this.constructor.name
-    this.status = status
-  }
-
-}
-
-/**
- * @param {Error} e the error to check
- * @param {number} [status] the protocol status to check, or any protocol error if undefined.
- * @returns {boolean} true if the given error is a protocol error with the given status.
- */
-export function isProtocolError(e, status) {
-  return (e instanceof ProtocolError && (status === undefined || e.status == status))
-}
-
-/**
- * Normalizes the given error into a protocol error; passes through input that is already
- * protocol errors.
- *
- * @param {unknown} cause some caught error
- * @returns {ProtocolError} an apporpriate protocol error
- */
-export function normalizeProtocolError(cause) {
-  if (cause instanceof ProtocolError)
-    return cause
-
-  if (cause instanceof ZodError)
-    return new ProtocolError(prettifyError(cause), 400, { cause })
-
-  if (cause instanceof Error || cause instanceof DOMException) {
-    if (cause.name === 'TimeoutError')
-      return new ProtocolError('operation timed out', 408, { cause })
-
-    if (cause.name === 'AbortError')
-      return new ProtocolError('operation was aborted', 499, { cause })
-
-    return new ProtocolError(cause.message, 500, { cause })
-  }
-
-  // fallback, unknown
-  const options = cause == undefined ? undefined : { cause: normalizeError(cause) }
-  return new ProtocolError(`Error! ${cause}`, 500, options)
-}
-
-/**
- * Error wrapper for unknown errors (not an Error?)
- *
- * @augments Error
- */
-export class NormalizedError extends Error {}
-
-/**
- * wrap the given failure error into an error; passes through input that is already an Error object.
- *
- * @param {unknown} failure some caught error
- * @returns {Error} an apporpriate error
- */
-export function normalizeError(failure) {
-  if (failure instanceof Error)
-    return failure
-
-  return new NormalizedError(`unnormalized failure ${failure}`)
-}

src/common/errors.spec.js src/common/errors.spec.ts

···
   ProtocolError,
   isProtocolError,
   normalizeProtocolError,
-} from '#common/errors.js'
+} from '#common/errors'
 
 describe('isProtocolError', () => {
   it('identifies protocol errors', () => {

src/common/errors.ts

···
+/** @module common */
+
+import { prettifyError, ZodError } from 'zod/v4'
+
+const StatusCodes: Record<number, string> = {
+  400: 'Bad Request',
+  401: 'Unauthorized',
+  403: 'Forbidden',
+  404: 'Not Found',
+  408: 'Request Timeout',
+  409: 'Conflict',
+  429: 'Too Many Requests',
+  499: 'Client Closed Request',
+  500: 'Internal Server Error',
+}
+
+/** Base error options interface */
+export interface BaseErrorOpts {
+  /** the cause of the error */
+  cause?: Error
+}
+
+/**
+ * Common base class for Skypod Errors
+ * only difference is that we explicitly type cause to be Error
+ */
+export class BaseError extends Error {
+
+  /** the cause of the error */
+  declare cause?: Error
+
+  constructor(message: string, options?: BaseErrorOpts) {
+    super(message, options)
+    if (options?.cause)
+      this.cause = normalizeError(options.cause)
+  }
+
+}
+
+/** Common base class for Websocket Errors */
+export class ProtocolError extends BaseError {
+
+  /** the HTTP status code representing this error */
+  status: number
+
+  constructor(message: string, status: number, options?: BaseErrorOpts) {
+    const statusText = StatusCodes[status] || 'Unknown'
+    super(`${status} ${statusText}: ${message}`, options)
+
+    this.name = this.constructor.name
+    this.status = status
+  }
+
+}
+
+/** Check if an error is a protocol error with optional status check */
+export function isProtocolError(e: Error, status?: number): e is ProtocolError {
+  return (e instanceof ProtocolError && (status === undefined || e.status == status))
+}
+
+/**
+ * Normalizes the given error into a protocol error
+ * passes through input that is already protocol errors.
+ */
+export function normalizeProtocolError(cause: unknown): ProtocolError {
+  if (cause instanceof ProtocolError)
+    return cause
+
+  if (cause instanceof ZodError)
+    return new ProtocolError(prettifyError(cause), 400, { cause })
+
+  if (cause instanceof Error || cause instanceof DOMException) {
+    if (cause.name === 'TimeoutError')
+      return new ProtocolError('operation timed out', 408, { cause })
+
+    if (cause.name === 'AbortError')
+      return new ProtocolError('operation was aborted', 499, { cause })
+
+    return new ProtocolError(cause.message, 500, { cause })
+  }
+
+  // fallback, unknown
+  const options = cause == undefined ? undefined : { cause: normalizeError(cause) }
+  return new ProtocolError(`Error! ${cause}`, 500, options)
+}
+
+/** Error wrapper for unknown errors (not an Error?) */
+export class NormalizedError extends Error {}
+
+/**
+ * wrap the given failure error into an error
+ * passes through input that is already an Error object.
+ */
+export function normalizeError(failure: unknown): Error {
+  if (failure instanceof Error)
+    return failure
+
+  return new NormalizedError(`unnormalized failure ${failure}`)
+}

src/common/protocol.js

···
-/** @module common/protocol */
-
-export * from './protocol/brands.js'
-export * from './protocol/messages.js'
-export * from './protocol/messages-preauth.js'
-export * from './protocol/messages-realm.js'
-
-import { z } from 'zod/v4'
-
-/**
- * A zod transformer for parsing Json
- *
- * @type {z.ZodTransform<object, string>}
- */
-export const parseJson = z.transform((input, ctx) => {
-  try {
-    return JSON.parse(input)
-  }
-  catch {
-    ctx.issues.push({
-      code: 'custom',
-      input,
-      message: 'input could not be parsed as JSON',
-    })
-
-    return z.NEVER
-  }
-})

src/common/protocol.ts

···
+/** @module common/protocol */
+
+export * from './protocol/brands'
+export * from './protocol/messages'
+export * from './protocol/messages-preauth'
+export * from './protocol/messages-realm'
+
+import { z } from 'zod/v4'
+
+/** A zod transformer for parsing json */
+export const parseJson: z.ZodTransform<unknown, string> = z.transform(
+  (input, ctx) => {
+    try {
+      return JSON.parse(input)
+    }
+    catch {
+      ctx.issues.push({
+        code: 'custom',
+        input,
+        message: 'input could not be parsed as JSON',
+      })
+
+      return z.NEVER
+    }
+  }
+)

src/common/protocol/brands.js

···
-import { z as z_types } from 'zod/v4'
-import { Brand } from '#common/schema/brand.js'
-
-export const IdentBrand = new Brand('ident')
-/** @typedef {z_types.infer<typeof IdentBrand.schema>} IdentID */
-
-export const RealmBrand = new Brand('realm')
-/** @typedef {z_types.infer<typeof RealmBrand.schema>} RealmID */

src/common/protocol/brands.ts

···
+import { Brand } from '#common/schema/brand'
+
+const ident = Symbol('ident')
+export const IdentBrand = new Brand<typeof ident>(ident, 'ident')
+export type IdentID = ReturnType<typeof IdentBrand.generate>
+
+const realm = Symbol('realm')
+export const RealmBrand = new Brand<typeof realm>(realm, 'realm')
+export type RealmID = ReturnType<typeof RealmBrand.generate>

src/common/protocol/messages-preauth.js src/common/protocol/messages-preauth.ts

···
 /** @module common/protocol */
 
 import { z } from 'zod/v4'
-import { jwkSchema } from '#common/crypto/jwks.js'
+import { jwkSchema } from '#common/crypto/jwks'
 
 /** zod schema for `preauth.authn` message */
 export const preauthRegisterMessageSchema = z.object({
   msg: z.literal('preauth.register'),
   pubkey: jwkSchema,
 })
-/** @typedef {z.infer<typeof preauthRegisterMessageSchema>} PreauthRegisterMessage */
+export type PreauthRegisterMessage = z.infer<typeof preauthRegisterMessageSchema>
 
 /** zod schema for `preauth.authn` message */
 export const preauthAuthnMessageSchema = z.object({
   msg: z.literal('preauth.authn'),
 })
-/** @typedef {z.infer<typeof preauthAuthnMessageSchema>} PreauthAuthnMessage */
+export type PreauthAuthnMessage = z.infer<typeof preauthAuthnMessageSchema>
 
 /** zod schema for any `preauth` messages */
 export const preauthMessageSchema = z.discriminatedUnion('msg', [
   preauthRegisterMessageSchema,
   preauthAuthnMessageSchema,
 ])
-/** @typedef {z.infer<typeof preauthMessageSchema>} PreauthMessage */
+export type PreauthMessage = z.infer<typeof preauthMessageSchema>

src/common/protocol/messages-realm.js

···
-import { z } from 'zod/v4'
-import { IdentBrand } from './brands.js'
-import { okResponseSchema } from './messages.js'
-
-/**
- * zod schema for `realm.broadcast` message
- * recipients = true, include self in broadcast
- * recipients = false, exclude self in broadcast (default)
- * recipients = [], use these exact recipients
- */
-export const realmBroadcastMessageSchema = z.object({
-  msg: z.literal('realm.broadcast'),
-  payload: z.any(),
-  recipients: z.union([
-    z.boolean(),
-    z.array(IdentBrand.schema),
-  ]).default(false),
-})
-/** @typedef {z.infer<typeof realmBroadcastMessageSchema>} RealmBroadcastMessage */
-
-// rtc messages
-
-export const realmRtcSignalMessageSchema = z.object({
-  msg: z.literal('realm.rtc.signal'),
-  payload: z.string(),
-  sender: IdentBrand.schema,
-  recipient: IdentBrand.schema,
-  initiator: z.boolean(),
-})
-/** @typedef {z.infer<typeof realmRtcSignalMessageSchema>} RealmRtcSignalMessage */
-
-export const realmRtcPeerWelcomeMessageSchema = okResponseSchema.extend({
-  msg: z.literal('realm.rtc.peer-welcome'),
-  peers: z.array(IdentBrand.schema),
-})
-/** @typedef {z.infer<typeof realmRtcPeerWelcomeMessageSchema>} RealmRtcPeerWelcomeMessage */
-
-export const realmRtcPeerJoinedMessageSchema = okResponseSchema.extend({
-  msg: z.literal('realm.rtc.peer-joined'),
-  identid: IdentBrand.schema,
-})
-/** @typedef {z.infer<typeof realmRtcPeerJoinedMessageSchema>} RealmRtcPeerJoinedMessage */
-
-export const realmRtcPeerLeftMessageSchema = okResponseSchema.extend({
-  msg: z.literal('realm.rtc.peer-left'),
-  identid: IdentBrand.schema,
-})
-/** @typedef {z.infer<typeof realmRtcPeerLeftMessageSchema>} RealmRtcPeerLeftMessage */
-
-/// useful unions
-
-export const realmToServerMessageSchema = z.discriminatedUnion('msg', [
-  realmBroadcastMessageSchema,
-  realmRtcSignalMessageSchema,
-])
-/** @typedef {z.infer<typeof realmToServerMessageSchema>} RealmToServerMessage */
-
-export const realmFromServerMessageSchema = z.discriminatedUnion('msg', [
-  realmRtcPeerJoinedMessageSchema,
-  realmRtcPeerLeftMessageSchema,
-  realmRtcSignalMessageSchema,
-])
-/** @typedef {z.infer<typeof realmFromServerMessageSchema>} RealmFromServerMessage */

src/common/protocol/messages-realm.ts

···
+import { z } from 'zod/v4'
+
+import { IdentBrand } from './brands'
+import { responseOkSchema } from './messages'
+
+/**
+ * zod schema for `realm.broadcast` message
+ *
+ * recipients = true, include self in broadcast
+ * recipients = false, exclude self in broadcast (default)
+ * recipients = [], use these exact recipients
+ */
+export const realmBroadcastMessageSchema = z.object({
+  msg: z.literal('realm.broadcast'),
+  payload: z.any(),
+  recipients: z.union([
+    z.boolean(),
+    z.array(IdentBrand.schema),
+  ]).default(false),
+})
+
+export type RealmBroadcastMessage = z.infer<typeof realmBroadcastMessageSchema>
+
+// rtc messages
+
+export const realmRtcSignalMessageSchema = z.object({
+  msg: z.literal('realm.rtc.signal'),
+  payload: z.string(),
+  sender: IdentBrand.schema,
+  recipient: IdentBrand.schema,
+  initiator: z.boolean(),
+})
+
+export const realmRtcPeerWelcomeMessageSchema = responseOkSchema.extend({
+  msg: z.literal('realm.rtc.peer-welcome'),
+  peers: z.array(IdentBrand.schema),
+})
+
+export const realmRtcPeerJoinedMessageSchema = responseOkSchema.extend({
+  msg: z.literal('realm.rtc.peer-joined'),
+  identid: IdentBrand.schema,
+})
+
+export const realmRtcPeerLeftMessageSchema = responseOkSchema.extend({
+  msg: z.literal('realm.rtc.peer-left'),
+  identid: IdentBrand.schema,
+})
+
+export type RealmRtcSignalMessage = z.infer<typeof realmRtcSignalMessageSchema>
+export type RealmRtcPeerWelcomeMessage = z.infer<typeof realmRtcPeerWelcomeMessageSchema>
+export type RealmRtcPeerJoinedMessage = z.infer<typeof realmRtcPeerJoinedMessageSchema>
+export type RealmRtcPeerLeftMessage = z.infer<typeof realmRtcPeerLeftMessageSchema>
+
+/// useful unions
+
+export const realmToServerMessageSchema = z.discriminatedUnion('msg', [
+  realmBroadcastMessageSchema,
+  realmRtcSignalMessageSchema,
+])
+
+export const realmFromServerMessageSchema = z.discriminatedUnion('msg', [
+  realmRtcPeerJoinedMessageSchema,
+  realmRtcPeerLeftMessageSchema,
+  realmRtcSignalMessageSchema,
+])
+
+export type RealmToServerMessage = z.infer<typeof realmToServerMessageSchema>
+export type RealmFromServerMessage = z.infer<typeof realmFromServerMessageSchema>

src/common/protocol/messages.js

···
-import { z } from 'zod/v4'
-
-/** zod schema for `ok` message */
-export const okResponseSchema = z.object({
-  ok: z.literal(true),
-})
-/** @typedef {z.infer<typeof okResponseSchema>} OkResponse */
-
-/** zod schema for `error` message */
-export const errorResponseSchema = z.object({
-  ok: z.literal(false),
-  status: z.number(),
-  message: z.string(),
-})
-/** @typedef {z.infer<typeof errorResponseSchema>} ErrorResponse */

src/common/protocol/messages.ts

···
+import { z } from 'zod/v4'
+
+/** zod schema for `ok` message */
+export const responseOkSchema = z.object({
+  ok: z.literal(true),
+})
+export type ResponseOk = z.infer<typeof responseOkSchema>
+
+/** zod schema for `error` message */
+export const responseErrorSchema = z.object({
+  ok: z.literal(false),
+  status: z.number(),
+  message: z.string(),
+})
+export type ErrorResponse = z.infer<typeof responseErrorSchema>

src/common/schema/brand.js

···
-/** @module common/schema */
-
-import { nanoid } from 'nanoid'
-import { z } from 'zod/v4'
-
-/**
- * A brand creates identifiers that are typesafe by construction,
- * and shouldn't be able to be passed to the wrong resource type.
- */
-export class Brand {
-
-  /**
-   * @private
-   * @typedef {z.core.$ZodBranded<z.ZodString, symbol>} BrandSchema
-   * @typedef {z.infer<BrandSchema>} BrandId
-   */
-
-  /** @type {string} */
-  #prefix
-
-  /** @type {number} */
-  #length
-
-  /** @type {BrandSchema} */
-  #schema
-
-  /**
-   * @param {string} prefix string prefix for the identifier, eg. "ident", "acct")
-   * @param {number} [length] the length of the random identifier part
-   */
-  constructor(prefix, length = 16) {
-    const brand = prefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') // escape regex chars
-    const pattern = new RegExp(`^${brand}-[A-Za-z0-9_-]{${length.toString()}}$`)
-
-    this.#prefix = brand
-    this.#length = length
-    this.#schema = z.string().regex(pattern).brand(Symbol(brand))
-  }
-
-  get schema() {
-    return this.#schema
-  }
-
-  /** @returns {BrandId} a generated identifier */
-  generate() {
-    const id = nanoid(this.#length)
-    return this.#schema.parse(`${this.#prefix}-${id}`)
-  }
-
-  /**
-   * @param {unknown} input the input to validate
-   * @returns {BrandId} a valid identifier
-   * @throws {z.ZodError} if the input could not be parsed
-   */
-  parse(input) {
-    return this.#schema.parse(input)
-  }
-
-  /**
-   * @param {unknown} input the input to validate
-   * @returns {boolean} true if a valid identifier, false otherwise
-   */
-  validate(input) {
-    return input != null
-      && typeof input === 'string'
-      && this.#schema.safeParse(input).success
-  }
-
-}

src/common/schema/brand.ts

···
+/** @module common/schema */
+
+import { nanoid } from 'nanoid'
+import { z } from 'zod/v4'
+
+export type Branded<T, B> = T & { __brand: B }
+
+/**
+ * A brand creates identifiers that are typesafe by construction,
+ * and shouldn't be able to be passed to the wrong resource type.
+ */
+export class Brand<B extends symbol> {
+
+  #prefix: string
+  #length: number
+  #schema
+
+  constructor(brand: B, prefix: string, length = 16) {
+    prefix = prefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') // escape regex chars
+    const pattern = new RegExp(`^${prefix}-[A-Za-z0-9_-]{${length.toString()}}$`)
+
+    this.#prefix = prefix
+    this.#length = length
+    this.#schema = z.string().regex(pattern).brand(brand)
+  }
+
+  get schema(): z.ZodType<Branded<string, B>> {
+    return this.#schema as unknown as z.ZodType<Branded<string, B>>
+  }
+
+  generate() {
+    const id = nanoid(this.#length)
+    return this.#schema.parse(`${this.#prefix}-${id}`) as Branded<string, B>
+  }
+
+  parse(input: unknown): Branded<string, B> {
+    return this.#schema.parse(input) as Branded<string, B>
+  }
+
+  /** @return a boolean if the string is valid */
+  validate(input: string): input is Branded<string, B>  {
+    return input != null && typeof input === 'string' && this.#schema.safeParse(input).success
+  }
+
+}

src/common/socket.js src/common/socket.ts

···
 /** @module common/socket */
 
-import * as z_types from 'zod/v4'
-
-import { combineSignals } from '#common/async/aborts.js'
-import { BlockingAtom } from '#common/async/blocking-atom.js'
-import { BlockingQueue } from '#common/async/blocking-queue.js'
-import { Breaker } from '#common/breaker.js'
-import { ProtocolError } from '#common/errors.js'
+import { combineSignals } from '#common/async/aborts'
+import { BlockingAtom } from '#common/async/blocking-atom'
+import { BlockingQueue } from '#common/async/blocking-queue'
+import { Breaker } from '#common/breaker'
+import { normalizeError, ProtocolError } from '#common/errors'
+import { z } from 'zod/v4'
 
 import { parseJson } from './protocol.js'
 
-/**
- * Send some data in JSON format down the wire.
- *
- * @param {WebSocket} ws the socket to send on
- * @param {unknown} data the data to send
- */
-export function sendSocket(ws, data) {
+/** Send some data in JSON format down the wire. */
+export function sendSocket(ws: WebSocket, data: unknown): void {
   ws.send(JSON.stringify(data))
 }
 
···
  *   if (ws.readyState !== ws.CLOSED)
  *     ws.close();
  * }
- *
- * @param {WebSocket} ws the socket to read
- * @param {AbortSignal} [signal] an abort signal to cancel the block
- * @returns {Promise<unknown>} the message off the socket
  */
-export async function takeSocket(ws, signal) {
+export async function takeSocket(ws: WebSocket, signal?: AbortSignal): Promise<unknown> {
   signal?.throwIfAborted()
 
   const atom = new BlockingAtom()
···
 /**
  * exactly take socket, but will additionally apply a json decoding
  *
- * @template T the schema's type
- * @param {WebSocket} ws the socket to read
- * @param {z_types.ZodSchema<T>} schema an a schema to execute
- * @param {AbortSignal} [signal] an abort signal to cancel the block
- * @returns {Promise<T>} the message off the socket
+ * @param ws the socket to read
+ * @param schema an a schema to execute
+ * @param [signal] an abort signal to cancel the block
+ * @returns the message off the socket
  */
-export async function takeSocketJson(ws, schema, signal) {
+export async function takeSocketJson<T>(ws: WebSocket, schema: z.ZodSchema<T>, signal?: AbortSignal): Promise<T> {
   const data = await takeSocket(ws, signal)
   return parseJson.pipe(schema).parseAsync(data)
 }
 
-/**
- * stream configuration options
- *
- * @typedef ConfigProps
- * @property {number} maxDepth max depth of the queue, after which messages are dropped
- * @property {AbortSignal} [signal] an abort signal to cancel the block
- */
+/** stream configuration options */
 
-/** @type {ConfigProps} */
-export const STREAM_CONFIG_DEFAULT = { maxDepth: 1000 }
+interface ConfigProps {
+    maxDepth: number
+    signal?: AbortSignal
+}
+
+export const STREAM_CONFIG_DEFAULT: ConfigProps = {
+  maxDepth: 1000
+}
 
 // symbols for iteration protocol
+
 const yield$ = Symbol('yield$')
 const error$ = Symbol('error$')
-const end$ = Symbol('end$')
+const end$   = Symbol('end$')
+
+type StreamYield =
+  | [typeof yield$, unknown]
+  | [typeof error$, Error]
+  | [typeof end$]
 
 /**
  * Given a websocket, stream messages off the socket as an async generator.
···
  *   if (ws.readyState !== ws.CLOSED)
  *     ws.close();
  * }
- *
- *
- *
- * @param {WebSocket} ws the socket to read
- * @param {Partial<ConfigProps>} [config_] stream configuration to merge into defaults
- * @yields {unknown} messages from the socket
  */
-export async function* streamSocket(ws, config_) {
-  const { signal, ...config } = { ...STREAM_CONFIG_DEFAULT, ...config_ }
+export async function* streamSocket(ws: WebSocket, config_?: Partial<ConfigProps>) {
+  const { signal, ...config } = { ...STREAM_CONFIG_DEFAULT, ...(config_ || {}) }
   signal?.throwIfAborted()
 
   // await incoming messages without blocking
-  /** @type {BlockingQueue<Array<*>>} */
-  const queue = new BlockingQueue(config.maxDepth)
+  const queue = new BlockingQueue<StreamYield>(config.maxDepth)
 
   // if true, we're ignoring incoming messages until we drop the queue
   let inBackoffMode = false
···
 
   // define callback functions (need to be able to reference for removing them)
 
-  /** @type {function(MessageEvent): void} */
-  const onMessage = breaker.untilTripped((m) => {
+  const onMessage = breaker.untilTripped((m: MessageEvent) => {
     if (inBackoffMode) {
       console.warn('ignoring incoming message due to backpressure protection!')
       return
···
     }
   })
 
-  /** @type {function(Event): void} */
   // todo: why are we getting this on client shutdown instead of onClose?
-  const onError = breaker.tripThen((e) => {
-    if (e.message === 'Unexpected EOF') {
-      queue.enqueue([end$])
-    }
-    else {
-      queue.enqueue([error$, e])
-    }
+  const onError = breaker.tripThen((e: Event) => {
+    queue.enqueue([error$, normalizeError(e)])
   })
 
-  /** @type {function(): void} */
   const onClose = breaker.tripThen(() => {
     queue.enqueue([end$])
   })
···
 /**
  * exactly stream socket, but will additionally apply a json decoding
  * messages not validating will end the stream with an error
- *
- * @param {WebSocket} ws the socket to read
- * @param {Partial<ConfigProps>} [config] stream configuration to merge into defaults
- * @returns {AsyncGenerator<unknown>} an async generator
- * @yields the message off the socket
  */
-export async function* streamSocketJson(ws, config) {
+export async function* streamSocketJson(ws: WebSocket, config?: Partial<ConfigProps>): AsyncGenerator<unknown> {
   for await (const message of streamSocket(ws, config)) {
     yield parseJson.parseAsync(message)
   }
···
 /**
  * exactly stream socket, but will additionally apply a json decoding
  * messages not validating will end the stream with an error
- *
- * @template T the schema's type
- * @param {WebSocket} ws the socket to read
- * @param {z_types.ZodSchema<T>} schema an a schema to execute
- * @param {Partial<ConfigProps>} [config] stream configuration to merge into defaults
- * @returns {AsyncGenerator<T>} an async generator
- * @yields the message off the socket
  */
-export async function* streamSocketSchema(ws, schema, config) {
+export async function* streamSocketSchema<T>(
+  ws: WebSocket,
+  schema: z.ZodSchema<T>,
+  config?: Partial<ConfigProps>,
+): AsyncGenerator<T> {
   const parser = parseJson.pipe(schema)
-
   for await (const message of streamSocket(ws, config)) {
     yield await parser.parseAsync(message)
   }

src/common/strict-map.js

···
-/** @module common */
-
-/**
- * A map with methods to ensure key presence and safe update.
- *
- * @template K, V
- * @augments {Map<K, V>}
- */
-export class StrictMap extends Map {
-
-  /**
-   * @param {K} key to lookup in the map, throwing is missing
-   * @returns {V} the value from the map
-   * @throws {Error} if the key is not present in the map
-   */
-  require(key) {
-    if (!this.has(key)) throw Error(`key is required but not in the map`)
-
-    const value = /** @type {V} */ (this.get(key))
-    return value
-  }
-
-  /**
-   * @param {K} key to lookup in the map
-   * @param {function(): V} maker a callback which will create the value in the map if not present.
-   * @returns {V} the value from the map, possibly newly created by {maker}
-   */
-  ensure(key, maker) {
-    if (!this.has(key)) {
-      this.set(key, maker())
-    }
-
-    return /** @type {V} */ (this.get(key))
-  }
-
-  /**
-   * @param {K} key to update in the map
-   * @param {function(V=): V | undefined} update
-   * function which returns the new value for the map
-   * if the return value is REMOVE_KEY, the whole entry in the map will be removed.
-   */
-  update(key, update) {
-    const prev = this.get(key)
-    const next = update(prev)
-
-    if (next === undefined) {
-      this.delete(key)
-    }
-    else {
-      this.set(key, next)
-    }
-  }
-
-}

src/common/strict-map.ts

···
+/** @module common */
+
+/** A map with methods to ensure key presence and safe update. */
+export class StrictMap<K, V> extends Map<K, V> {
+
+  /**
+   * Get a value from the map, throwing if missing
+   * @throws {Error} if the key is not present in the map
+   */
+  require(key: K): V {
+    if (!this.has(key)) throw Error(`key is required but not in the map`)
+
+    const value = this.get(key)!
+    return value
+  }
+
+  /** Get a value from the map, creating it if not present */
+  ensure(key: K, maker: () => V): V {
+    if (!this.has(key)) {
+      this.set(key, maker())
+    }
+
+    return this.get(key)!
+  }
+
+  /** Update a value in the map, removing if undefined is returned */
+  update(key: K, update: (prev?: V) => V | undefined): void {
+    const prev = this.get(key)
+    const next = update(prev)
+
+    if (next === undefined) {
+      this.delete(key)
+    }
+    else {
+      this.set(key, next)
+    }
+  }
+
+}

src/common/types.js src/common/types.ts

···
 
 /**
  * A callback function, with arbitrary arguments; use {Parameters} to extract them.
- *
- * @typedef {function(...*): void} Callback
  */
+export type Callback = (...args: any[]) => void
 
 /**
  * A callback function with no arguments.
- *
- * @typedef {function(): void} VoidCallback
  */
+export type VoidCallback = () => void
 
 const output = NEVER
 export default output

src/server/index.js src/server/index.ts

···
 import * as http from 'http'
 import { WebSocketServer } from 'ws'
 
-import { apiRouter } from './routes-api/middleware.js'
-import { socketHandler } from './routes-socket/handler.js'
-import { makeStaticMiddleware, makeSpaMiddleware } from './routes-static.js'
-import { notFoundHandler } from './routes-error.js'
-
-/** @typedef {typeof http.IncomingMessage} Input */
+import { apiRouter } from './routes-api/middleware'
+import { socketHandler } from './routes-socket/handler'
+import { makeStaticMiddleware, makeSpaMiddleware } from './routes-static'
+import { notFoundHandler } from './routes-error'
 
 /**
  * configures an http server which hosts the SPA and websocket endpoint
  *
- * @param {string} root the path to the root public/ directory
- * @returns {http.Server<Input>} a configured server
+ * @param root the path to the root public/ directory
+ * @returns a configured server
  */
-export function buildServer(root) {
+export function buildServer(root: string): http.Server<typeof http.IncomingMessage> {
   const app = express()
   const server = http.createServer(app)
 

src/server/routes-error.js

···
-import * as express_types from 'express'
-
-/** @type {express_types.RequestHandler} */
-export const notFoundHandler = (req, res) => {
-  console.log(req.url)
-  res.status(404).send('wut')
-}

src/server/routes-error.ts

···
+import * as express from 'express'
+
+export const notFoundHandler: express.RequestHandler = (req, res) => {
+  console.log(req.url)
+  res.status(404).send('wut')
+}

src/server/routes-socket/handler-preauth.js

···
-import { combineSignals, timeoutSignal } from '#common/async/aborts.js'
-import { jwkImport } from '#common/crypto/jwks.js'
-import { jwtPayload, verifyJwtToken } from '#common/crypto/jwts.js'
-import { normalizeError, ProtocolError } from '#common/errors.js'
-import { IdentBrand, preauthMessageSchema, RealmBrand } from '#common/protocol.js'
-import { takeSocket } from '#common/socket.js'
-
-import * as protocol_types from '#common/protocol.js'
-import * as realms from './state.js'
-
-/**
- * immediately after the socket connects, we up to 3 seconds for a valid authentication message.
- * - if the realm does not exist (by realm id), we create a new one, and add the identity (success).
- * - if the realm /does/ exist, we verify the message is a signed JWT our already registered pubkey.
- *
- * @param {WebSocket} ws the websocket we're controlling
- * @param {AbortSignal} [signal] a signal to abort blocking on the socket
- * @returns {Promise<realms.AuthenticatedConnection>} the now authenticated identity
- */
-export async function preauthHandler(ws, signal) {
-  const timeout = timeoutSignal(3000)
-  const combinedSignal = combineSignals(signal, timeout.signal)
-
-  try {
-    const data = await takeSocket(ws, combinedSignal)
-
-    // if any of the parsing fails, it'll throw a zod error
-    const jwt = await jwtPayload(preauthMessageSchema).parseAsync(data)
-    const identid = IdentBrand.parse(jwt.claims.iss)
-    const realmid = RealmBrand.parse(jwt.claims.aud)
-
-    // if we're registering, make sure the realm exists
-    if (jwt.payload.msg === 'preauth.register') {
-      const registrantkey = await jwkImport.parseAsync(jwt.payload.pubkey)
-      realms.ensureRegisteredRealm(realmid, identid, registrantkey)
-    }
-
-    return authenticatePreauth(realmid, identid, jwt.token)
-  }
-  finally {
-    timeout.cancel()
-  }
-}
-
-/**
- * @param {protocol_types.RealmID} realmid the realm id to lookup
- * @param {protocol_types.IdentID} identid the identity id to authenticate against
- * @param {string} token the (still encoded) JWT to verify
- * @returns {Promise<realms.AuthenticatedConnection>} an authenticated connection from this token
- * @throws {ProtocolError} when the token isn't validly signed or the identity is unrecognized
- */
-async function authenticatePreauth(realmid, identid, token) {
-  try {
-    const realm = realms.realmMap.require(realmid)
-    const pubkey = realm.identities.require(identid)
-
-    // at this point we no langer care about the payload
-    // but this throws as a side-effect if the token is invalid
-    await verifyJwtToken(token, pubkey)
-    return { realmid, realm, identid, pubkey }
-  }
-  catch (exc) {
-    const err = normalizeError(exc)
-    throw new ProtocolError('jwt verification failed', 401, { cause: err })
-  }
-}

src/server/routes-socket/handler-preauth.ts

···
+import { combineSignals, timeoutSignal } from '#common/async/aborts'
+import { jwkImport } from '#common/crypto/jwks'
+import { jwtPayload, verifyJwtToken } from '#common/crypto/jwts'
+import { normalizeError, ProtocolError } from '#common/errors'
+import { IdentBrand, IdentID, preauthMessageSchema, RealmBrand, RealmID } from '#common/protocol'
+import { takeSocket } from '#common/socket'
+
+import * as realms from './state'
+
+/**
+ * immediately after the socket connects, we up to 3 seconds for a valid authentication message.
+ * - if the realm does not exist (by realm id), we create a new one, and add the identity (success).
+ * - if the realm /does/ exist, we verify the message is a signed JWT our already registered pubkey.
+ */
+export async function preauthHandler(ws: WebSocket, signal?: AbortSignal): Promise<realms.AuthenticatedIdentity> {
+  const timeout = timeoutSignal(3000)
+  const combinedSignal = combineSignals(signal, timeout.signal)
+
+  try {
+    const data = await takeSocket(ws, combinedSignal)
+
+    // if any of the parsing fails, it'll throw a zod error
+    const jwt = await jwtPayload(preauthMessageSchema).parseAsync(data)
+    const identid = IdentBrand.parse(jwt.claims.iss)
+    const realmid = RealmBrand.parse(jwt.claims.aud)
+
+    // if we're registering, make sure the realm exists
+    if (jwt.payload.msg === 'preauth.register') {
+      const registrantkey = await jwkImport.parseAsync(jwt.payload.pubkey)
+      realms.ensureRegisteredRealm(realmid, identid, registrantkey)
+    }
+
+    return authenticatePreauth(realmid, identid, jwt.token)
+  }
+  finally {
+    timeout.cancel()
+  }
+}
+
+async function authenticatePreauth(realmid: RealmID, identid: IdentID, token: string): Promise<realms.AuthenticatedIdentity> {
+  try {
+    const realm = realms.realmMap.require(realmid)
+    const pubkey = realm.identities.require(identid)
+
+    // at this point we no langer care about the payload
+    // but this throws as a side-effect if the token is invalid
+    await verifyJwtToken(token, pubkey)
+    return { realmid, realm, identid, pubkey }
+  }
+  catch (exc) {
+    const err = normalizeError(exc)
+    throw new ProtocolError('jwt verification failed', 401, { cause: err })
+  }
+}

src/server/routes-socket/handler-realm.js src/server/routes-socket/handler-realm.ts

···
-import { normalizeProtocolError, ProtocolError } from '#common/errors.js'
-import { realmToServerMessageSchema, parseJson } from '#common/protocol.js'
-import { sendSocket, streamSocket } from '#common/socket.js'
+import { normalizeProtocolError, ProtocolError } from '#common/errors'
 
-import * as protocol_types from '#common/protocol.js'
-import * as realm_types from '#server/routes-socket/state.js'
+import * as protocol from '#common/protocol'
+import { sendSocket, streamSocket } from '#common/socket.js'
+import * as realm from '#server/routes-socket/state'
 
 /**
  * ance we've retrieved authentication details, we go into the main realm loop.
  * read messages as they come in and dispatch actions.
- *
- * @param {WebSocket} ws the websockt we're handling
- * @param {realm_types.AuthenticatedConnection} auth the authenticated identity we're representing
- * @param {AbortSignal} [signal] an optional signal to abort the blocking loop
  */
-export async function realmHandler(ws, auth, signal) {
+export async function realmHandler(ws: WebSocket, auth: realm.AuthenticatedIdentity, signal?: AbortSignal) {
   realmBroadcast(auth, buildRtcPeerJoined(auth))
   sendSocket(ws, buildRtcPeerWelcome(auth))
 
+  const parser = protocol.parseJson
+    .pipe(protocol.realmToServerMessageSchema)
+
   try {
     for await (const data of streamSocket(ws, { signal })) {
       try {
-        const msg = await parseJson.pipe(realmToServerMessageSchema).parseAsync(data)
+        const msg = await parser.parseAsync(data)
         switch (msg.msg) {
           case 'realm.broadcast':
             realmBroadcast(auth, msg.payload, msg.recipients)
···
   }
 }
 
-/**
- * @private
- * @param {realm_types.AuthenticatedConnection} auth the current identity
- * @returns {protocol_types.RealmRtcPeerWelcomeMessage} a realm welcome response
- */
-function buildRtcPeerWelcome(auth) {
+function buildRtcPeerWelcome(auth: realm.AuthenticatedIdentity): protocol.RealmRtcPeerWelcomeMessage {
   return {
     ok: true,
     msg: 'realm.rtc.peer-welcome',
···
   }
 }
 
-/**
- * @private
- * @param {realm_types.AuthenticatedConnection} auth the current identity
- * @returns {protocol_types.RealmRtcPeerJoinedMessage} a realm status response
- */
-function buildRtcPeerJoined(auth) {
+function buildRtcPeerJoined(auth: realm.AuthenticatedIdentity): protocol.RealmRtcPeerJoinedMessage {
   return {
     ok: true,
     msg: 'realm.rtc.peer-joined',
···
   }
 }
 
-/**
- * @private
- * @param {realm_types.AuthenticatedConnection} auth the current identity
- * @returns {protocol_types.RealmRtcPeerLeftMessage} a realm status response
- */
-function buildRtcPeerLeft(auth) {
+function buildRtcPeerLeft(auth: realm.AuthenticatedIdentity): protocol.RealmRtcPeerLeftMessage {
   return {
     ok: true,
     msg: 'realm.rtc.peer-left',
···
   }
 }
 
-/**
- * @private
- * @param {ProtocolError} error the error to report
- * @returns {protocol_types.ErrorResponse} a realm error response
- */
-function buildRealmError(error) {
+function buildRealmError(error: ProtocolError): protocol.ErrorResponse {
   return {
     ok: false,
     message: error.message,
···
  * when false, send to the whole realm, excluding self
  * when an array of recipients, send to those recipients explicitly
  */
-function realmBroadcast(auth, payload, recipients) {
+function realmBroadcast(auth: realm.AuthenticatedIdentity, payload: unknown, recipients: protocol.IdentID[] | boolean = false) {
   const echo = recipients === true || Array.isArray(recipients)
   const recips = Array.isArray(recipients) ? recipients : Array.from(auth.realm.identities.keys())
 

src/server/routes-socket/handler.js src/server/routes-socket/handler.ts

···
 import { format } from 'node:util'
 
-import { normalizeError, normalizeProtocolError } from '#common/errors.js'
+import { normalizeError, normalizeProtocolError } from '#common/errors'
 
-import { preauthHandler } from './handler-preauth.js'
-import { realmHandler } from './handler-realm.js'
-import { attachSocket, detachSocket } from './state.js'
+import { preauthHandler } from './handler-preauth'
+import { realmHandler } from './handler-realm'
+import { attachSocket, detachSocket } from './state'
 
-/**
- * when the socket connects, we drive our protocol through handlers.
- *
- * @param {WebSocket} ws the websocket to control
- */
-export async function socketHandler(ws) {
+/** when the socket connects, we drive our protocol through handlers. */
+export async function socketHandler(ws: WebSocket) {
   console.log('WebSocket connection established')
 
   try {

src/server/routes-socket/state.js

···
-import { StrictMap } from '#common/strict-map.js'
-import * as protocol_types from '#common/protocol.js'
-
-/**
- * An authenticated identity; only handed out in response to successful authentication.
- *
- * @typedef {object} AuthenticatedConnection
- * @property {protocol_types.RealmID} realmid the realm this connection is associated with
- * @property {protocol_types.IdentID} identid the identity this connection is associated with
- * @property {Realm} realm the actual realm from the realm map
- * @property {CryptoKey} pubkey the connected identity's public key
- */
-
-/**
- * @typedef {object} Realm
- * @property {protocol_types.RealmID} realmid the realm's id
- * @property {StrictMap<protocol_types.IdentID, Array<WebSocket>>} sockets
- * a map of identity id to open sockets.
- * @property {StrictMap<protocol_types.IdentID, CryptoKey>} identities
- * a map of identity id to the realm's known public key for that identity.
- */
-
-/** @type {StrictMap<protocol_types.RealmID, Realm>} */
-export const realmMap = new StrictMap()
-
-/**
- * gets or creates a registered realm, with the given identity and key
- * as initial registrants in a newly created realm. If the realm already
- * exists, it's not changed.
- *
- * @param {protocol_types.RealmID} realmid the realm id to ensure exists
- * @param {protocol_types.IdentID} registrantid the identity id of the registrant
- * @param {CryptoKey} registrantkey the public key of the registrant
- * @returns {Realm} a registered realm, possibly newly created with the registrant
- */
-export function ensureRegisteredRealm(realmid, registrantid, registrantkey) {
-  const realm = realmMap.ensure(realmid, () => ({
-    realmid,
-    sockets: new StrictMap(),
-    identities: new StrictMap([[registrantid, registrantkey]]),
-  }))
-
-  // hack for now, allow any registration to work
-  realm.identities.ensure(registrantid, () => registrantkey)
-  return realm
-}
-
-/**
- * @param {Realm} realm the realm on which to attach the socket
- * @param {protocol_types.IdentID} ident the identity which owns the socket
- * @param {WebSocket} socket the socket to attach
- */
-export function attachSocket(realm, ident, socket) {
-  realm.sockets.update(ident, ss => (ss ? [...ss, socket] : [socket]))
-}
-
-/**
- * @param {Realm} realm the realm from which to detach the socket
- * @param {protocol_types.IdentID} ident the identity which owns the socket
- * @param {WebSocket} socket the socket to dettach
- */
-export function detachSocket(realm, ident, socket) {
-  realm.sockets.update(ident, (sockets) => {
-    const next = sockets?.filter(s => s !== socket)
-    return next?.length ? next : undefined
-  })
-}

src/server/routes-socket/state.ts

···
+import { IdentID, RealmID } from '#common/protocol.js'
+import { StrictMap } from '#common/strict-map'
+
+/** An authenticated identity; only handed out in response to successful authentication. */
+export interface AuthenticatedIdentity {
+  realm: Realm
+  realmid: RealmID
+  identid: IdentID
+  pubkey: CryptoKey
+}
+
+export interface Realm {
+  realmid: RealmID
+  sockets: StrictMap<IdentID, WebSocket[]>
+  identities: StrictMap<IdentID, CryptoKey>
+}
+
+export const realmMap = new StrictMap<RealmID, Realm>()
+
+/**
+ * gets or creates a registered realm, with the given identity and key
+ * as initial registrants in a newly created realm. If the realm already
+ * exists, it's not changed.
+ *
+ * @param realmid the realm id to ensure exists
+ * @param registrantid the identity id of the registrant
+ * @param registrantkey the public key of the registrant
+ * @returns a registered realm, possibly newly created with the registrant
+ */
+export function ensureRegisteredRealm(realmid: RealmID, registrantid: IdentID, registrantkey: CryptoKey): Realm {
+  const realm = realmMap.ensure(realmid, () => ({
+    realmid,
+    sockets: new StrictMap(),
+    identities: new StrictMap([[registrantid, registrantkey]]),
+  }))
+
+  // hack for now, allow any registration to work
+  realm.identities.ensure(registrantid, () => registrantkey)
+  return realm
+}
+
+export function attachSocket(realm: Realm, ident: IdentID, socket: WebSocket) {
+  realm.sockets.update(ident, ss => (ss ? [...ss, socket] : [socket]))
+}
+
+export function detachSocket(realm: Realm, ident: IdentID, socket: WebSocket) {
+  realm.sockets.update(ident, (sockets) => {
+    const next = sockets?.filter(s => s !== socket)
+    return next?.length ? next : undefined
+  })
+}

src/server/routes-static.js

···
-import * as express_types from 'express'
-import express from 'express'
-import { join } from 'path'
-
-/**
- * @typedef {object} StaticOpts
- * @property {string} root the root directory to staticly server
- * @property {string} index the index file to use if given a directory or spa path
- */
-
-/**
- * returns a configured static middleware
- *
- * @param {StaticOpts} opts options for corfiguring the middleware
- * @returns {express_types.RequestHandler} a new middleware
- */
-export function makeStaticMiddleware(opts) {
-  return express.static(opts.root, { index: opts.index })
-}
-
-/**
- * returns the index file for any GET request for text/html it matches
- *
- * @param {StaticOpts} opts options for configuring the middleware
- * @returns {express_types.RequestHandler} a new middleware
- */
-export function makeSpaMiddleware(opts) {
-  return (req, res, next) => {
-    if (req.method === 'GET' && req.accepts('text/html')) {
-      return res.sendFile(join(opts.root, opts.index))
-    }
-
-    next() // otherwise
-  }
-}

src/server/routes-static.ts

···
+import express from 'express'
+import { join } from 'path'
+
+interface StaticOpts {
+  root: string
+  index: string
+}
+
+/**
+ * returns a configured static middleware
+ *
+ * @param opts options for corfiguring the middleware
+ * @returns a new middleware
+ */
+export function makeStaticMiddleware(opts: StaticOpts): express.RequestHandler {
+  return express.static(opts.root, { index: opts.index })
+}
+
+/**
+ * returns the index file for any GET request for text/html it matches
+ *
+ * @param opts options for configuring the middleware
+ * @returns a new middleware
+ */
+export function makeSpaMiddleware(opts: StaticOpts): express.RequestHandler {
+  return (req, res, next) => {
+    if (req.method === 'GET' && req.accepts('text/html')) {
+      return res.sendFile(join(opts.root, opts.index))
+    }
+
+    next() // otherwise
+  }
+}

tsconfig.json

···
 {
   "compilerOptions": {
-    // Type checking for JavaScript files
-    "allowJs": true,
-    "checkJs": true,
+    // tsx compatibility
+    "moduleDetection": "force",
     "noEmit": true,
 
     // Modern JavaScript support
     "target": "es2024",
-    "module": "ESNext",
+    "module": "Preserve",
     "moduleResolution": "bundler",
     "allowSyntheticDefaultImports": true,
     "esModuleInterop": true,