4bnode 4.1.8 → 4.2.0

package/skeleton/.4bnode/assets/js/pages/DiscoveryPage.js

@@ -0,0 +1,231 @@
+import React, { useState, useEffect } from "react";
+import { LuWifi, LuRefreshCw } from "react-icons/lu";
+import { html, api, copyToClipboard } from "../lib.js";
+import { useApp } from "../context.js";
+
+const STATUS_BADGE = {
+  advertising: { cls: "badge-success", label: "Advertising" },
+  idle: { cls: "badge-muted", label: "Idle" },
+  error: { cls: "badge-error", label: "Error" },
+  unsupported: { cls: "badge-warning", label: "Not installed" },
+};
+
+export function DiscoveryPage() {
+  const { toast } = useApp();
+  const [info, setInfo] = useState(null);
+  const [loading, setLoading] = useState(true);
+  const [saving, setSaving] = useState(false);
+  const [toggling, setToggling] = useState(false);
+  const [name, setName] = useState("");
+  const [type, setType] = useState("http");
+  const [enabled, setEnabled] = useState(true);
+
+  const [browseType, setBrowseType] = useState("http");
+  const [services, setServices] = useState(null);
+  const [browsing, setBrowsing] = useState(false);
+
+  async function loadInfo() {
+    setLoading(true);
+    try {
+      const r = await api("/discovery");
+      setInfo(r);
+      setName((r.config && r.config.name) || "");
+      setType((r.config && r.config.type) || "http");
+      setEnabled(r.enabled !== false);
+    } catch (err) {
+      toast(err.message, "error");
+    }
+    setLoading(false);
+  }
+
+  useEffect(() => {
+    loadInfo();
+  }, []);
+
+  // Flip Bonjour on/off immediately — no "Save" step. The dashboard runs in the
+  // same process as the advertiser, so the server re-publishes / unpublishes live
+  // and persists BONJOUR_ENABLED to .env in one call.
+  async function handleToggle(e) {
+    const next = e.target.checked;
+    setEnabled(next); // optimistic
+    setToggling(true);
+    try {
+      await api("/discovery/config", { method: "POST", body: { enabled: next } });
+      toast(next ? "Bonjour enabled" : "Bonjour disabled", "success");
+      loadInfo();
+    } catch (err) {
+      setEnabled(!next); // revert on failure
+      toast(err.message, "error");
+    }
+    setToggling(false);
+  }
+
+  async function handleSave() {
+    setSaving(true);
+    try {
+      const r = await api("/discovery/config", {
+        method: "POST",
+        body: { enabled, name, type },
+      });
+      toast(r.message || "Saved", "success");
+      loadInfo();
+    } catch (err) {
+      toast(err.message, "error");
+    }
+    setSaving(false);
+  }
+
+  async function handleBrowse() {
+    setBrowsing(true);
+    setServices(null);
+    try {
+      const r = await api("/discovery/browse?type=" + encodeURIComponent(browseType || "http"));
+      if (!r.available) {
+        toast("bonjour-service is not installed", "error");
+        setServices([]);
+      } else {
+        setServices(r.services || []);
+      }
+    } catch (err) {
+      toast(err.message, "error");
+      setServices([]);
+    }
+    setBrowsing(false);
+  }
+
+  const self = info && info.self;
+  const available = info && info.available;
+  const status = self ? self.status : "idle";
+  const badge = STATUS_BADGE[status] || STATUS_BADGE.idle;
+
+  return html`<div>
+    <div className="flex items-center justify-between mb-4">
+      <div>
+        <div className="card-title">Discovery</div>
+        <div className="card-subtitle">
+          Bonjour / mDNS — advertise this app and find others on your network
+        </div>
+      </div>
+      <button className="btn btn-ghost btn-sm" onClick=${loadInfo} disabled=${loading}>
+        <span className="sidebar-icon"><${LuRefreshCw} size=${14} /></span> Refresh
+      </button>
+    </div>
+
+    ${loading && !info
+      ? html`<div className="card"><div className="empty-state" style=${{ padding: "40px" }}><p>Loading…</p></div></div>`
+      : html`<div style=${{ display: "grid", gridTemplateColumns: "repeat(auto-fit, minmax(340px, 1fr))", gap: "20px", alignItems: "start" }}>
+          <!-- This app -->
+          <div className="card">
+            <div className="flex items-center justify-between mb-3">
+              <div className="card-title">This app</div>
+              <span className=${`badge ${badge.cls}`}>${badge.label}</span>
+            </div>
+
+            ${!available
+              ? html`<div>
+                  <p className="text-sm text-muted mb-2">
+                    Local network discovery needs the <code>bonjour-service</code> package.
+                    Install it, then restart the app:
+                  </p>
+                  <div className="code-block" style=${{ display: "flex", alignItems: "center", justifyContent: "space-between", gap: "8px" }}>
+                    <code>npm install bonjour-service</code>
+                    <button className="btn btn-ghost btn-sm" onClick=${() => { copyToClipboard("npm install bonjour-service"); toast("Copied", "success"); }}>Copy</button>
+                  </div>
+                </div>`
+              : html`<div>
+                  <!-- Enable / disable — applies instantly, no restart -->
+                  <div style=${{ display: "flex", alignItems: "center", justifyContent: "space-between", gap: "12px", padding: "10px 12px", border: "1px solid var(--border)", borderRadius: "8px", marginBottom: "14px" }}>
+                    <div>
+                      <div style=${{ fontSize: "13px", fontWeight: 600 }}>Advertise on local network</div>
+                      <div className="text-muted" style=${{ fontSize: "12px" }}>
+                        ${enabled ? "On — this app is discoverable via Bonjour/mDNS" : "Off — not broadcasting on the network"}
+                      </div>
+                    </div>
+                    <label className="form-toggle">
+                      <input type="checkbox" checked=${enabled} disabled=${toggling} onChange=${handleToggle} />
+                      <span className="slider"></span>
+                    </label>
+                  </div>
+
+                  ${status === "advertising"
+                    ? html`<div style=${{ display: "grid", gridTemplateColumns: "90px 1fr", gap: "6px 12px", fontSize: "13px", marginBottom: "12px" }}>
+                        <span className="text-muted">Name</span><span>${self.name}</span>
+                        <span className="text-muted">Address</span>
+                        <span style=${{ fontFamily: "monospace" }}>
+                          <a href=${`http://${self.host}:${self.port}`} target="_blank" rel="noreferrer">${self.host}:${self.port}</a>
+                        </span>
+                        <span className="text-muted">Service</span><span style=${{ fontFamily: "monospace" }}>_${self.type}._tcp.local</span>
+                        ${self.txt ? Object.entries(self.txt).map(([k, v]) => html`
+                          <span key=${k} className="text-muted">txt · ${k}</span><span>${String(v)}</span>`) : null}
+                      </div>`
+                    : html`<p className="text-sm text-muted mb-2">
+                        ${status === "error"
+                          ? html`Advertising failed: <span style=${{ color: "var(--danger, #e5484d)" }}>${self.error}</span>`
+                          : enabled
+                            ? "Not advertising yet — restart the app to start."
+                            : "Advertising is disabled (BONJOUR_ENABLED=off)."}
+                      </p>`}
+
+                  <div style=${{ borderTop: "1px solid var(--border)", margin: "4px 0 14px" }}></div>
+
+                  <div className="form-group" style=${{ opacity: enabled ? 1 : 0.55 }}>
+                    <label className="form-label">Service name</label>
+                    <input className="form-input" value=${name} placeholder="My App (auto: app + hostname)" onInput=${(e) => setName(e.target.value)} />
+                  </div>
+                  <div className="form-group">
+                    <label className="form-label">Service type</label>
+                    <input className="form-input" value=${type} placeholder="http" onInput=${(e) => setType(e.target.value)} />
+                  </div>
+                  <button className="btn btn-primary" onClick=${handleSave} disabled=${saving}>
+                    ${saving ? html`<span className="spinner" />` : null}
+                    ${saving ? "Saving…" : "Save settings"}
+                  </button>
+                  <p className="text-sm text-muted" style=${{ marginTop: "8px" }}>
+                    Changes apply immediately — no restart needed.
+                  </p>
+                </div>`}
+          </div>
+
+          <!-- Browse the network -->
+          <div className="card">
+            <div className="card-title mb-1">Network</div>
+            <div className="card-subtitle mb-3">Discover other Bonjour services on this LAN</div>
+            <div className="flex items-center gap-2 mb-3" style=${{ display: "flex", gap: "8px" }}>
+              <input className="form-input" style=${{ maxWidth: "160px" }} value=${browseType}
+                placeholder="http" onInput=${(e) => setBrowseType(e.target.value)}
+                onKeyDown=${(e) => e.key === "Enter" && handleBrowse()} />
+              <button className="btn btn-primary" onClick=${handleBrowse} disabled=${browsing}>
+                ${browsing ? html`<span className="spinner" />` : html`<span className="sidebar-icon"><${LuWifi} size=${14} /></span>`}
+                ${browsing ? "Scanning…" : "Browse"}
+              </button>
+            </div>
+
+            ${services === null
+              ? html`<div className="empty-state" style=${{ padding: "28px" }}>
+                  <div className="empty-icon"><${LuWifi} size=${30} /></div>
+                  <p>Browse for <code>_${browseType || "http"}._tcp</code> services on your network.</p>
+                </div>`
+              : services.length === 0
+                ? html`<div className="empty-state" style=${{ padding: "28px" }}>
+                    <p>No services found. Discovery only works on the same local network, and firewalls blocking UDP 5353 will silently hide services.</p>
+                  </div>`
+                : html`<div className="routes-list">
+                    ${services.map((s) => html`<div key=${`${s.name}|${s.host}|${s.port}`} className="route-item">
+                      <div style=${{ display: "flex", flexDirection: "column", gap: "4px", flex: 1, minWidth: 0 }}>
+                        <span className="ri-name">${s.name}</span>
+                        <span className="ri-file" style=${{ fontFamily: "monospace" }}>${s.host}:${s.port}${s.addresses && s.addresses.length ? ` · ${s.addresses.join(", ")}` : ""}</span>
+                        ${s.txt && Object.keys(s.txt).length
+                          ? html`<span className="ri-file" style=${{ opacity: 0.7 }}>${Object.entries(s.txt).map(([k, v]) => `${k}=${v}`).join("  ")}</span>`
+                          : null}
+                      </div>
+                      <a className="btn btn-ghost btn-sm" href=${`http://${s.host}:${s.port}`} target="_blank" rel="noreferrer">Open</a>
+                    </div>`)}
+                  </div>`}
+
+            <p className="text-sm text-muted" style=${{ marginTop: "12px" }}>
+              mDNS is local-network only — it can't bridge Wi-Fi and cellular, and guest networks with client isolation block it.
+            </p>
+          </div>
+        </div>`}
+  </div>`;
+}

package/skeleton/.4bnode/codegen.js

@@ -854,6 +854,7 @@ export const PACKAGE_VERSIONS = {
   multer: "^1.4.5-lts.1",
   nodemailer: "^6.9.0",
   resend: "^4.0.0",
+  "bonjour-service": "^1.4.3",
 };
 
 // Add packages to package.json (dependencies, or devDependencies when dev:true).
@@ -1572,3 +1573,324 @@ export default { sendMail, emailTemplate, verifyMailer };
 `;
 }
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Bonjour / mDNS service discovery
+//
+// First-class, single-source concept: the runtime module below is the canonical
+// definition. skeleton/src/discovery.js is generated from buildDiscoveryModule()
+// (a test asserts they're identical), and both the CLI (add-bonjour) and the
+// /_dev dashboard write / wire from this same source — so nothing can drift.
+//
+// The module is deliberately backtick-free so it embeds cleanly here without
+// escaping. It advertises the app on the LAN and can browse for peers, with the
+// hard-won mDNS pitfalls (bare hostnames, IPs in TXT, missing goodbye packets)
+// all designed out. See the module header for the full rationale.
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function buildDiscoveryModule() {
+  return `// Bonjour / mDNS service discovery
+// Zero-config LAN networking: this app advertises itself so other devices can
+// find it by name (host.local) without hard-coded IPs, and can browse for other
+// services on the same network.
+//
+// This module is written to be defensive and robust. The lessons baked in here
+// are exactly the ones that make mDNS silently fail in the wild:
+//
+//   - bonjour-service is imported LAZILY. A project that has not installed it (or
+//     runs somewhere the native mDNS socket cannot bind) still boots fine;
+//     advertising just becomes a no-op in an "unsupported" state.
+//   - The SRV host is ALWAYS explicitly .local-suffixed. os.hostname() alone can
+//     return a bare name (e.g. "MSI" on Windows), which routes address lookups to
+//     unicast DNS instead of multicast DNS and never resolves.
+//   - Only STABLE metadata goes in the TXT record (platform, app name). Putting
+//     per-restart / per-interface data like an IP in TXT produces conflicting
+//     duplicate records; some clients (notably iOS NWBrowser) then silently never
+//     resolve the service, with no error and no timeout.
+//   - A single service instance is kept at a time; re-advertising (e.g. after a
+//     port change) stops the old one first so the network never sees duplicates.
+//   - Clean shutdown sends TTL=0 "goodbye" packets so stale records do not linger
+//     in client caches for the record's full TTL (can be over an hour).
+//
+// Configure via .env:  BONJOUR_ENABLED=off | BONJOUR_NAME=... | BONJOUR_TYPE=http
+
+import os from "os";
+
+let bonjour = null; // shared mDNS controller (created lazily, one per process)
+let published = null; // handle to the currently-advertised service, if any
+let BonjourCtor = null; // cached constructor after the first successful import
+
+let selfState = {
+  status: "idle", // idle | advertising | error | unsupported
+  name: null,
+  type: null,
+  port: null,
+  host: null,
+  txt: null,
+  error: null,
+};
+
+// Import bonjour-service on demand. Returns the constructor, or null if the
+// package is not installed / cannot load. Handles both the named (Bonjour) and
+// default export shapes across versions.
+async function loadBonjour() {
+  if (BonjourCtor) return BonjourCtor;
+  try {
+    const mod = await import("bonjour-service");
+    BonjourCtor =
+      mod.Bonjour ||
+      mod.default ||
+      (mod.default && mod.default.Bonjour) ||
+      null;
+    return BonjourCtor;
+  } catch {
+    return null;
+  }
+}
+
+// Always .local-suffixed, single-label host so address lookups use mDNS.
+function localHostname() {
+  const base = (os.hostname() || "device").split(".")[0].trim() || "device";
+  return base + ".local";
+}
+
+// Build a network-unique default service name. Two apps scaffolded from the same
+// skeleton on different machines would otherwise collide on the same name.
+function defaultServiceName() {
+  // An explicit BONJOUR_NAME is used verbatim — the user owns uniqueness.
+  if (process.env.BONJOUR_NAME) return process.env.BONJOUR_NAME;
+  // Auto name: project name + hostname, so two machines don't collide.
+  const base = process.env.APP_NAME || process.env.npm_package_name || "4bnode-app";
+  const host = (os.hostname() || "").split(".")[0].replace(/[^a-zA-Z0-9-]/g, "");
+  return host ? base + " (" + host + ")" : base;
+}
+
+// On by default; opt out with BONJOUR_ENABLED=off.
+export function isDiscoveryEnabled() {
+  return process.env.BONJOUR_ENABLED !== "off";
+}
+
+// Snapshot of what this process is currently advertising (read by the dashboard).
+export function getSelfState() {
+  return { ...selfState, enabled: isDiscoveryEnabled() };
+}
+
+// Advertise this app on the local network. Safe to call repeatedly; each call
+// replaces any prior advertisement, so a port change re-publishes cleanly. Must
+// be called AFTER the HTTP server is actually listening (so the port is bound).
+export async function startAdvertising({ port, name, type } = {}) {
+  if (!isDiscoveryEnabled()) {
+    selfState = { ...selfState, status: "idle", error: null };
+    return getSelfState();
+  }
+  if (!port) return getSelfState();
+
+  const Ctor = await loadBonjour();
+  if (!Ctor) {
+    selfState = {
+      status: "unsupported",
+      name: null,
+      type: null,
+      port: null,
+      host: null,
+      txt: null,
+      error: "bonjour-service not installed",
+    };
+    console.log(
+      "mDNS: bonjour-service not installed - LAN discovery disabled. Run: npm install bonjour-service to enable.",
+    );
+    return getSelfState();
+  }
+
+  // Replace any previous advertisement so two conflicting records never coexist.
+  await stopAdvertising();
+  if (!bonjour) bonjour = new Ctor();
+
+  const serviceName = name || defaultServiceName();
+  const serviceType = type || process.env.BONJOUR_TYPE || "http";
+  const host = localHostname();
+  const txt = {
+    platform: os.platform(), // stable across restarts - safe for TXT
+    app: process.env.APP_NAME || process.env.npm_package_name || "4bnode-app",
+  };
+
+  try {
+    published = bonjour.publish({ name: serviceName, type: serviceType, port, host, txt });
+    selfState = {
+      status: "advertising",
+      name: serviceName,
+      type: serviceType,
+      port,
+      host,
+      txt,
+      error: null,
+    };
+    published.on("up", () => {
+      console.log(
+        "mDNS: advertising " + JSON.stringify(serviceName) + " at " + host + ":" + port + " (_" + serviceType + "._tcp.local)",
+      );
+    });
+    published.on("error", (err) => {
+      const msg = String((err && err.message) || err);
+      selfState = { ...selfState, status: "error", error: msg };
+      console.warn(
+        "mDNS: advertising error - " + msg + ". If discovery is not working, check that UDP port 5353 is not blocked by a firewall.",
+      );
+    });
+  } catch (err) {
+    selfState = { ...selfState, status: "error", error: String((err && err.message) || err) };
+  }
+  return getSelfState();
+}
+
+// Stop advertising and send the TTL=0 goodbye packets. Resolves once the mDNS
+// responder has flushed them (or after a short safety timeout, so a stuck
+// responder can never hang process shutdown).
+export function stopAdvertising() {
+  return new Promise((resolve) => {
+    if (!bonjour) {
+      published = null;
+      return resolve();
+    }
+    let done = false;
+    const finish = () => {
+      if (done) return;
+      done = true;
+      published = null;
+      if (selfState.status === "advertising") selfState = { ...selfState, status: "idle" };
+      resolve();
+    };
+    try {
+      bonjour.unpublishAll(finish); // constructs + sends goodbye packets
+      const t = setTimeout(finish, 1500);
+      if (t.unref) t.unref();
+    } catch {
+      finish();
+    }
+  });
+}
+
+// Full teardown for process shutdown: goodbye packets, then destroy the socket.
+export async function destroyDiscovery() {
+  await stopAdvertising();
+  try {
+    if (bonjour) bonjour.destroy();
+  } catch {}
+  bonjour = null;
+}
+
+// Browse the LAN for services of a given type. Collects results for timeoutMs
+// (de-duplicated, excluding our own advertisement), then stops the browser and
+// resolves. "available" is false when bonjour-service is not installed.
+export async function browse({ type = "http", timeoutMs = 2500 } = {}) {
+  const Ctor = await loadBonjour();
+  if (!Ctor) return { available: false, services: [] };
+  if (!bonjour) bonjour = new Ctor();
+
+  return new Promise((resolve) => {
+    const found = new Map();
+    let browser = null;
+    let settled = false;
+
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      try {
+        if (browser && typeof browser.stop === "function") browser.stop();
+      } catch {}
+      resolve({ available: true, services: Array.from(found.values()) });
+    };
+
+    try {
+      browser = bonjour.find({ type }, (service) => {
+        // Exclude our own advertisement from the peer list.
+        if (published && selfState.name && service.name === selfState.name) return;
+        const key = service.name + "|" + service.host + "|" + service.port;
+        found.set(key, {
+          name: service.name,
+          host: service.host,
+          port: service.port,
+          type: service.type,
+          protocol: service.protocol,
+          addresses: Array.isArray(service.addresses) ? service.addresses : [],
+          txt: service.txt || {},
+          fqdn: service.fqdn || null,
+        });
+      });
+    } catch (err) {
+      settled = true;
+      return resolve({ available: true, services: [], error: String((err && err.message) || err) });
+    }
+
+    const t = setTimeout(finish, Math.max(500, Math.min(10000, Number(timeoutMs) || 2500)));
+    if (t.unref) t.unref();
+  });
+}
+`;
+}
+
+// Import line that exposes the discovery lifecycle to index.js.
+export const DISCOVERY_IMPORT =
+  'import { startAdvertising, destroyDiscovery } from "./src/discovery.js";';
+
+// Idempotently wire Bonjour/mDNS advertising + graceful shutdown into an existing
+// index.js. Safe to run repeatedly and on apps that predate the built-in wiring:
+// each of the three edits is guarded, so re-running (or running on the current
+// skeleton, which already ships wired) is a no-op.
+export function wireDiscoveryIntoIndex(content) {
+  let out = content;
+
+  // 1. import (after the last import)
+  if (!out.includes("./src/discovery.js")) {
+    out = addImportAfterLastImport(out, DISCOVERY_IMPORT);
+  }
+
+  // 2. advertise as soon as the server is listening
+  if (!out.includes("startAdvertising(")) {
+    const call =
+      "\n    // Advertise on the local network via Bonjour/mDNS (after the port is bound).\n" +
+      "    startAdvertising({ port: typeof tryPort !== 'undefined' ? tryPort : Number(port) }).catch(() => {});";
+    if (out.includes('listener.on("listening", () => {')) {
+      out = out.replace('listener.on("listening", () => {', 'listener.on("listening", () => {' + call);
+    } else if (out.includes("listener.on('listening', () => {")) {
+      out = out.replace("listener.on('listening', () => {", "listener.on('listening', () => {" + call);
+    } else {
+      // Generic Express app.listen(port, () => { ... }) / function () { ... }
+      const m = out.match(/(app\.listen\([^,]+,\s*(?:async\s*)?(?:function\s*)?\([^)]*\)\s*(?:=>\s*)?\{)/);
+      if (m) out = out.replace(m[1], m[1] + call);
+    }
+  }
+
+  // 3. graceful shutdown so goodbye packets are sent on a clean exit
+  if (!out.includes("destroyDiscovery(")) {
+    const shutdown = [
+      "",
+      "// Graceful shutdown - unpublish the Bonjour service (sends TTL=0 goodbye",
+      "// packets) so clients drop the stale record immediately on a clean exit.",
+      "let _bnShuttingDown = false;",
+      "async function _bnGracefulShutdown(signal) {",
+      "  if (_bnShuttingDown) return;",
+      "  _bnShuttingDown = true;",
+      "  try { await destroyDiscovery(); } catch {}",
+      "  process.exit(0);",
+      "}",
+      'process.on("SIGINT", () => _bnGracefulShutdown("SIGINT"));',
+      'process.on("SIGTERM", () => _bnGracefulShutdown("SIGTERM"));',
+      "// nodemon restarts by sending SIGUSR2 — unpublish first (so no stale record",
+      "// lingers across dev restarts), then re-raise so nodemon does the restart.",
+      'process.once("SIGUSR2", async () => {',
+      "  try { await destroyDiscovery(); } catch {}",
+      '  process.kill(process.pid, "SIGUSR2");',
+      "});",
+      "",
+    ].join("\n");
+    const m = out.match(/^startServer\(/m);
+    if (m) {
+      out = out.slice(0, m.index) + shutdown + "\n" + out.slice(m.index);
+    } else {
+      out = out.trimEnd() + "\n" + shutdown + "\n";
+    }
+  }
+
+  return out;
+}
+

package/skeleton/.4bnode/dev-api.js

@@ -1318,6 +1318,94 @@ router.post('/api/security/rate-limit', (req, res) => {
   }
 });
 
+// ---------------------------------------------------------------------------
+// Bonjour / mDNS discovery — advertise this app + browse the LAN
+// ---------------------------------------------------------------------------
+// The advertising itself lives in src/discovery.js and runs inside THIS process
+// (started by index.js). We load that exact module by absolute path so the
+// dashboard reads the very same live state — not a second, disconnected copy.
+function loadDiscovery() {
+  const url = pathToFileURL(path.join(process.cwd(), 'src', 'discovery.js')).href;
+  return import(url);
+}
+const safeServiceType = (t) => String(t || '').toLowerCase().replace(/[^a-z0-9-]/g, '').slice(0, 20);
+
+// Current advertisement state + whether mDNS is available in this project.
+router.get('/api/discovery', async (req, res) => {
+  try {
+    const envPath = path.join(process.cwd(), '.env');
+    const enabled = getEnvValue(envPath, 'BONJOUR_ENABLED') !== 'off';
+    const name = getEnvValue(envPath, 'BONJOUR_NAME');
+    const type = getEnvValue(envPath, 'BONJOUR_TYPE') || 'http';
+    const mod = await loadDiscovery().catch(() => null);
+    const self = mod && mod.getSelfState ? mod.getSelfState() : null;
+    res.json({ available: !!mod, enabled, config: { name, type }, self });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+// Browse the local network for services of a given type.
+router.get('/api/discovery/browse', async (req, res) => {
+  try {
+    const mod = await loadDiscovery().catch(() => null);
+    if (!mod || !mod.browse) return res.json({ available: false, services: [] });
+    const type = safeServiceType(req.query.type) || 'http';
+    const result = await mod.browse({ type, timeoutMs: 2500 });
+    res.json(result);
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+// Persist discovery settings to .env AND apply them live. Because the discovery
+// module runs in this very process, we can re-advertise immediately instead of
+// waiting for a restart: mutate the live process.env (so isDiscoveryEnabled and
+// the auto-name reflect the change), then re-publish / unpublish in place.
+router.post('/api/discovery/config', async (req, res) => {
+  try {
+    const envPath = path.join(process.cwd(), '.env');
+    const b = req.body || {};
+    if (typeof b.enabled === 'boolean') {
+      const v = b.enabled ? 'on' : 'off';
+      updateEnvFile(envPath, 'BONJOUR_ENABLED', v);
+      process.env.BONJOUR_ENABLED = v;
+    }
+    if (typeof b.name === 'string') {
+      const clean = b.name.replace(/[\r\n]/g, '').trim().slice(0, 63);
+      updateEnvFile(envPath, 'BONJOUR_NAME', clean);
+      process.env.BONJOUR_NAME = clean;
+    }
+    if (typeof b.type === 'string' && b.type.trim()) {
+      const t = safeServiceType(b.type) || 'http';
+      updateEnvFile(envPath, 'BONJOUR_TYPE', t);
+      process.env.BONJOUR_TYPE = t;
+    }
+
+    // Apply live in the running process.
+    let self = null;
+    const mod = await loadDiscovery().catch(() => null);
+    if (mod) {
+      if (process.env.BONJOUR_ENABLED === 'off') {
+        if (mod.stopAdvertising) await mod.stopAdvertising();
+      } else if (mod.startAdvertising) {
+        const st = mod.getSelfState ? mod.getSelfState() : {};
+        const port = st.port || Number(process.env.PORT) || (req.socket && req.socket.localPort);
+        await mod.startAdvertising({
+          port,
+          name: process.env.BONJOUR_NAME || undefined,
+          type: process.env.BONJOUR_TYPE || undefined,
+        });
+      }
+      self = mod.getSelfState ? mod.getSelfState() : null;
+    }
+
+    res.json({ message: 'Discovery settings applied.', self });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
 // ---------------------------------------------------------------------------
 // Email (nodemailer) — provider presets, SMTP config in .env, install + test
 // ---------------------------------------------------------------------------

package/skeleton/.env.example

@@ -15,6 +15,16 @@ NODE_ENV=development
 RATE_LIMIT_WINDOW_MS=900000
 RATE_LIMIT_MAX=500
 
+# ── Bonjour / mDNS service discovery ──
+# The app advertises itself on the local network so other devices can find it by
+# name (http://<host>.local:<port>) without hard-coded IPs. On by default.
+# BONJOUR_ENABLED: "off" disables advertising entirely.
+# BONJOUR_NAME:    custom service name shown to other devices (default: app + host).
+# BONJOUR_TYPE:    service type without the leading underscore (default: "http").
+# BONJOUR_ENABLED=off
+# BONJOUR_NAME=My App
+# BONJOUR_TYPE=http
+
 # ── Dev dashboard (/_dev) — a REMOTE-CODE-EXECUTION surface; keep it local-only ──
 # _4BNODE_DASHBOARD:    "on" force-enable (even in production — avoid); "off" disable.
 #                       Default: enabled only when NODE_ENV is not "production".