@devioarts/capacitor-mdns 0.1.0 → 0.2.0

package/docs/playground.md

@@ -1,11 +1,13 @@
 # Playground
 
 The `playground` directory is the maintained example app for this package.
+Its application identifier is `com.devioarts.pg.cap` on iOS, Android and Electron.
 
 It demonstrates:
 
-- starting and stopping an mDNS advertisement;
-- discovering services by type and optional name;
+- starting, updating and stopping an mDNS advertisement with JSON TXT records;
+- discovering services by type and optional name, with visible addresses and TXT;
+- watching several service types, with live service lists, found/lost logs and runtime errors;
 - using the Electron preload bridge;
 - checking `getPluginPlatform()` so you can confirm which runtime implementation handled a call.
 
@@ -17,3 +19,32 @@ npm run dev
 ```
 
 For Electron, use the playground together with `devioarts/capacitor-electron`.
+
+If native folders are missing after cloning, create the required platform first with `npx cap add ios`, `npx cap add android`, or `npx cap-electron add` inside `playground`.
+
+For native builds, build the plugin first from the repository root (`npm run build`), then:
+
+```shell
+cd playground
+npm run build:vite
+npx cap sync
+npm run open-ios       # or npm run open-android
+```
+
+On macOS, the sync hook adds the Local Network usage description and the default `_http._tcp`, `_airplay._tcp` and `_googlecast._tcp` Bonjour types to the generated iOS project, preserving any existing description and custom types. Add other types to `NSBonjourServices` before testing them on iOS.
+
+For Electron use `npm run build` followed by `npm run open-electron` inside `playground`. The build synchronizes the plugin registry before compiling, including all six methods and the three watch events. The default development origin is `http://localhost:5173`.
+A regular browser displays the UI but cannot perform mDNS; unsupported calls show an error.
+
+To test continuous discovery:
+
+1. Publish `_http._tcp.` with TXT on one device. Keep both devices on the same Wi-Fi network.
+2. On the other device, open Discovery and start watching `_http._tcp., _airplay._tcp., _googlecast._tcp.`.
+3. Check the live name, type, port, IP addresses and TXT. Publish a second type and check both appear.
+4. Stop a publisher and check its lost event and removal. Abrupt disappearance can take until its advertised TTL expires.
+5. Run a one-time search while watching, then stop watching and verify the publisher stays active.
+6. Stop the watch, change the types and start again. Switching tabs keeps both operations active; use their Stop buttons for independent cleanup.
+
+Use dots in the advertised name and hyphens in a name filter to verify equivalent matching.
+Run a long search and click Replace search to test replacement; the older request is logged as an error.
+The Logger panel shows full event snapshots, including the last snapshot on loss.

package/docs/runtime-behavior.md

@@ -1,5 +1,35 @@
 # Runtime behavior
 
+## Continuous discovery
+
+- `watchServices({ types })` is available on iOS, Android and Electron. A nonempty array of valid
+  `_name._tcp.` / `_name._udp.` types is required. Types are trimmed, trailing dots appended and
+  duplicates merged. Invalid input leaves the current watch running.
+- One watch group is active. A valid replacement first stops the old group. `watchersStarted`
+  counts requested native browsers; asynchronous startup failures arrive through `watchError`.
+- Register `serviceFound`, `serviceLost` and `watchError` listeners before starting. Found/lost
+  contain `{ service }` with `name`, full `type`, `domain`, `port`, `hosts` and optional `txt` /
+  `hostname`. Found is emitted only after a numeric address resolves. `hosts` is always an array. Lost uses the last resolved snapshot, and is emitted
+  only if the service was reported as found. A disappearance during resolve cancels that candidate.
+- Each service emits found once per period of presence. Lost carries the last resolved snapshot;
+  this API does not promise continuous updates or separate events for address or TXT changes.
+- A browser / transport failure stops the watch group and emits `{ type, errorMessage,
+  watching: false }`. Native resolve errors retry up to three times, then emit the same event with
+  `watching: true`; a later discovery can retry that service again.
+- `stopWatching()` returns `{ watching: false, error, errorMessage }`, suppresses old callbacks and
+  cancels browsers, pending resolves and retries. Stop failures are reported and cleanup can be
+  retried. It does not stop an advertisement or one-shot discovery. Native manager destruction
+  also closes the watch group.
+- Android watch groups and one-shot discovery share the pre-API-34 resolver queue and hold separate
+  references to the Wi-Fi multicast lock. Resolved NSD TXT attributes are returned as UTF-8 strings.
+- Electron observes Bonjour goodbye packets and PTR TTL expiry. It refreshes browse queries every
+  30 seconds and checks expiry every second. Detection after abrupt network loss depends on the
+  peer's advertised TTL. Late address packets update the cached snapshot.
+- A regular web browser returns `error: true` for watch startup; stop is an idempotent no-op.
+  The manual Electron preload bridge forwards all three event types and supports listener removal.
+
+## One-shot discovery and advertising
+
 - All methods resolve with the documented result shape. Runtime failures are reported through
   `error` and `errorMessage` instead of rejecting when the platform bridge can recover safely.
 - `getPluginPlatform()` resolves to `ios`, `android`, `electron`, or `web` from the implementation
@@ -8,7 +38,43 @@
   not report publish success or failure, the operation is stopped and returned as an error.
 - Only one advertisement is active at a time. Starting a new advertisement stops the previous one.
 - Discovery is timeboxed and cleans up native listeners, browsers, service-info callbacks, and
-  resolvers after completion. Overlapping discovery calls are serialized or safely replace the
-  previous native session so stale callbacks cannot complete a newer request.
+  resolvers after completion. A valid new discovery replaces the previous request with `error: true` and an empty list on every platform. Invalid requests leave the active search running.
+- Without a name filter, discovery waits for the entire timeout. A matching resolved service with an IP address can finish a filtered search early. A candidate without an address is not returned. Any discovery error discards partial results on every platform.
 - `stopBroadcast()` is idempotent and safe to call repeatedly, including after failed or timed-out
   publish attempts.
+- Android and Electron wait for stop confirmation. A failed or timed-out stop returns `error: true`
+  and `publishing: true` because the service may still be active. The registration is retained for
+  cleanup, and a replacement advertisement is not started until stopping succeeds.
+- On Android versions before T extension 7, mDNS operations hold a reference-counted Wi-Fi
+  multicast lock. Overlapping publishing and discovery keep separate references, so completing
+  discovery does not disable multicast for the active advertisement. Failed publish/stop attempts
+  release their lock reference while retaining any registration needed for late cleanup.
+- iOS IPv6 addresses with an interface scope retain it as a `%<scope-id>` suffix.
+- All platforms return IPv4 addresses before IPv6, retaining discovery order within each family.
+  Electron removes exact duplicate address strings from both discovery and watch snapshots.
+  Android retains the scope suffix provided by the OS. Electron's Bonjour library may return
+  link-local IPv6 without an interface scope; sorting does not make those addresses usable on an
+  IPv6-only network. Try suitable addresses rather than treating `hosts[0]` as a reachability guarantee.
+- On iOS a denied Local Network permission makes `discover()` report an error instead of returning an
+  empty list after the timeout.
+- Android resolves discovered services one at a time before API 34 (a platform limit of
+  `NsdManager.resolveService`); on API 34+ resolves run concurrently.
+- Service types use `_name._tcp.` or `_name._udp.` (optional trailing dot). The service label has 1–15 ASCII letters/digits/hyphens, includes a letter, starts and ends with a letter or digit, and has no consecutive hyphens. Types are trimmed and lowercased; absent or blank types default to `_http._tcp.` for broadcast/discover. Watch entries must be nonblank.
+- Broadcast names default to `DevIOArtsMDNS` on all platforms, are trimmed, contain no control characters and fit in 63 UTF-8 bytes. Name filters use normalized prefix matching: dots and hyphens compare equally and a final ` (n)` suffix is ignored. Returned names preserve actual advertised spelling. Bonjour on Electron changes dots to hyphens when publishing; native platforms can retain dots.
+- Ports must be integer numbers from 1 to 65535. Timeout defaults to 3000 ms; nonnumeric or non-finite values are errors, fractions are truncated and delays clamped to 0–2147483647 ms.
+- TXT publication works on all three platforms. Values must be strings. Keys must be nonempty printable ASCII without `=`, unique ignoring ASCII case. Each UTF-8 `key=value` entry fits in 255 bytes; the complete TXT record fits in 1300 bytes including the length byte for each entry (the common Android limit). Validation runs before replacing a broadcast.
+- Android cancels an unconfirmed registration immediately through its original listener; it does not wait indefinitely for a publish confirmation. Failed cancellation is retained for a stop retry.
+- Electron reports name conflicts immediately when Bonjour stops its probe; it does not rename the
+  service. A service stopped during its probe sends no goodbye records, so a rejected duplicate does
+  not evict the original service from other browsers. Once announcement records have been prepared,
+  stopping sends goodbye even if the send callback and `up` event have not arrived yet. Stopped
+  services ignore late announcement attempts. This behavior is tested with Bonjour 1.4.0;
+  the supported dependency range is `~1.4.0`.
+- Electron creates the Bonjour socket only when the first network operation starts. A failed response
+  to an incoming query is logged and leaves publication, discovery and watches running. Transport
+  `error` events remain fatal: they fail pending operations and stop watches. After a fatal transport
+  error, destroy the instance and create a new one.
+- On a fresh iOS installation, the Local Network prompt may outlast a discovery or publish timeout;
+  the system may also report denial before the user answers. The plugin does not distinguish a
+  pending permission prompt from explicit denial. Explain why access is needed, then allow the user
+  to retry the operation after granting it. This first-run sequence still needs physical-device testing.

package/electron/dist/plugin-settings.js

@@ -1,14 +1,21 @@
 'use strict';
 
 /**
- * Metadata consumed by the capacitor-electron runtime generator (`npm run update`).
+ * Metadata consumed by the capacitor-electron runtime generator (`npx cap-electron sync`).
  *
  * Import path for the JS layer: `@devioarts/capacitor-mdns/electron/settings`.
  */
 const pluginSettings = {
     pluginClass: 'mDNS',
-    pluginMethods: ['getPluginPlatform', 'startBroadcast', 'stopBroadcast', 'discover'],
-    pluginEvents: [],
+    pluginMethods: [
+        'getPluginPlatform',
+        'startBroadcast',
+        'stopBroadcast',
+        'discover',
+        'watchServices',
+        'stopWatching',
+    ],
+    pluginEvents: ['serviceFound', 'serviceLost', 'watchError'],
 };
 
 exports.pluginSettings = pluginSettings;

package/electron/dist/plugin-settings.js.map

@@ -1 +1 @@
-{"version":3,"file":"plugin-settings.js","sources":["../build/electron/src/plugin-settings.js"],"sourcesContent":["/**\n * Metadata consumed by the capacitor-electron runtime generator (`npm run update`).\n *\n * Import path for the JS layer: `@devioarts/capacitor-mdns/electron/settings`.\n */\nexport const pluginSettings = {\n    pluginClass: 'mDNS',\n    pluginMethods: ['getPluginPlatform', 'startBroadcast', 'stopBroadcast', 'discover'],\n    pluginEvents: [],\n};\n//# sourceMappingURL=plugin-settings.js.map"],"names":[],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACY,MAAC,cAAc,GAAG;AAC9B,IAAI,WAAW,EAAE,MAAM;AACvB,IAAI,aAAa,EAAE,CAAC,mBAAmB,EAAE,gBAAgB,EAAE,eAAe,EAAE,UAAU,CAAC;AACvF,IAAI,YAAY,EAAE,EAAE;AACpB;;;;"}
+{"version":3,"file":"plugin-settings.js","sources":["../build/electron/src/plugin-settings.js"],"sourcesContent":["/**\n * Metadata consumed by the capacitor-electron runtime generator (`npx cap-electron sync`).\n *\n * Import path for the JS layer: `@devioarts/capacitor-mdns/electron/settings`.\n */\nexport const pluginSettings = {\n    pluginClass: 'mDNS',\n    pluginMethods: [\n        'getPluginPlatform',\n        'startBroadcast',\n        'stopBroadcast',\n        'discover',\n        'watchServices',\n        'stopWatching',\n    ],\n    pluginEvents: ['serviceFound', 'serviceLost', 'watchError'],\n};\n//# sourceMappingURL=plugin-settings.js.map"],"names":[],"mappings":";;AAAA;AACA;AACA;AACA;AACA;AACY,MAAC,cAAc,GAAG;AAC9B,IAAI,WAAW,EAAE,MAAM;AACvB,IAAI,aAAa,EAAE;AACnB,QAAQ,mBAAmB;AAC3B,QAAQ,gBAAgB;AACxB,QAAQ,eAAe;AACvB,QAAQ,UAAU;AAClB,QAAQ,eAAe;AACvB,QAAQ,cAAc;AACtB,KAAK;AACL,IAAI,YAAY,EAAE,CAAC,cAAc,EAAE,aAAa,EAAE,YAAY,CAAC;AAC/D;;;;"}