docs: add CONTRIBUTING.md, CHANGELOG.md, and JSDoc to entire codebase

Add docs/CONTRIBUTING.md covering the build system, dev workflow, all
npm scripts, how to add new native host message types, code style, and
debugging guidance.

Add CHANGELOG.md at the project root documenting all features and fixes
across the 1.0.0 release.

Add JSDoc (@param, @returns) to all previously undocumented exported
functions across 35 JS files:
- native-host/holesail-manager/ (index, virtual-hosts, service-tunnels,
  servers, port-allocator)
- native-host top-level managers (startup, connect-proxy, https-proxy,
  certificate-authority, ssh-manager, rdp-manager)
- extension/background/ (logs, native-messaging, proxy, message-router)
- extension/dashboard/core/ (utils, navigation, init)
- extension/dashboard/ui/ (modal, toast, state-tag)
- extension/dashboard/pages/ (all 10 page files)
- extension/dashboard/refresh.js, events.js
- extension/dashboard/data/hostname-validator.js
- scripts/ (build-host, run-install)

native-host/holesail-manager/virtual-hosts.js

@@ -28,6 +28,14 @@ let _getAutoReconnect = null;
 const RECONNECT_BASE_MS = 5000;
 const RECONNECT_MAX_MS = 120000;
 
+/**
+ * Inject shared dependencies from the parent holesail-manager.
+ * Must be called once before any other function in this module.
+ * @param {Function} saveStateFn - Callback that persists the current state to disk.
+ * @param {Function} emitFn - Callback to emit tunnel lifecycle events to the extension.
+ * @param {Function} getReadyTimeoutMsFn - Returns the configured ready-timeout in ms (0 = no timeout).
+ * @param {Function} getAutoReconnectFn - Returns whether auto-reconnect is enabled.
+ */
 function init(saveStateFn, emitFn, getReadyTimeoutMsFn, getAutoReconnectFn) {
   _saveState = saveStateFn;
   _emit = emitFn;
@@ -62,6 +70,16 @@ function readyWithTimeout(hs, label) {
   });
 }
 
+/**
+ * Create or replace a virtual host tunnel.
+ * Connects to the remote Holesail peer and binds it to a dynamically allocated
+ * local port so the HTTPS proxy can forward browser requests to it.
+ * If a tunnel already exists for the hostname it is closed and replaced.
+ * @param {object} payload
+ * @param {string} payload.hostname - The virtual hostname (e.g. `myapp.hs`). Normalised to lowercase.
+ * @param {string} payload.hsUrl - The hs:// key of the remote peer.
+ * @returns {Promise<{ok: boolean, hostname?: string, localHost?: string, localPort?: number, state?: string, error?: string}>}
+ */
 async function setVirtualHost(payload) {
   let hostname = (payload.hostname || payload.hostName || '').trim();
   hostname = hostname.replace(/^https?:\/\//i, '').replace(/[/:?#].*$/, '').toLowerCase().trim();
@@ -111,6 +129,12 @@ async function setVirtualHost(payload) {
   }
 }
 
+/**
+ * Remove a virtual host, close its tunnel, and release its local port.
+ * @param {object} payload
+ * @param {string} payload.hostname - The hostname to remove.
+ * @returns {Promise<{ok: boolean, error?: string}>}
+ */
 async function removeVirtualHost(payload) {
   const hostname = payload.hostname || payload.hostName;
   debugLog('removeVirtualHost: hostname=', hostname);
@@ -125,6 +149,10 @@ async function removeVirtualHost(payload) {
   return { ok: true };
 }
 
+/**
+ * Return a snapshot of all virtual hosts (including errored/closed ones).
+ * @returns {Array<{hostname: string, hsUrl: string, localHost: string|null, localPort: number|null, state: string, createdAt: number}>}
+ */
 function getVirtualHosts() {
   const list = [];
   for (const [hostname, v] of virtualHosts) {
@@ -133,11 +161,22 @@ function getVirtualHosts() {
   return list;
 }
 
+/**
+ * Return the local tunnel port for a hostname, or null if not ready.
+ * @param {string} hostname
+ * @returns {number|null}
+ */
 function getLocalPortForHostname(hostname) {
   const v = virtualHosts.get(hostname);
   return v && v.localPort != null ? v.localPort : null;
 }
 
+/**
+ * Return the `{ host, port }` backend object for the HTTPS proxy SNI resolver,
+ * or null if the virtual host does not exist or is not yet ready.
+ * @param {string} hostname
+ * @returns {{host: string, port: number}|null}
+ */
 function getLocalBackend(hostname) {
   const v = virtualHosts.get(hostname);
   const out = (!v || v.localPort == null) ? null : { host: v.localHost ?? '127.0.0.1', port: v.localPort };
@@ -153,6 +192,11 @@ function getVirtualHostMap() {
   return m;
 }
 
+/**
+ * Cancel all reconnect timers and close all virtual host tunnels.
+ * Called during native host shutdown.
+ * @returns {Promise<void>}
+ */
 async function cleanupVirtualHosts() {
   for (const [, v] of virtualHosts) {
     if (v.reconnectTimer) { clearTimeout(v.reconnectTimer); v.reconnectTimer = null; }