Feature: expose validated per-device plugin settings endpoints

[MaxRink]

Feature: expose validated per-device plugin settings endpoints

Context

The native Skale USB setting in #716 is device-specific behavior. The retained native work keeps USB provenance in internal/settings state and does not make it a public plugin metadata field.

The current draft #849 introduces a broader manifest and native UI contract: a driver may declare an endpoint that owns its per-device settings. No existing issue covers this manifest/API/UI boundary.

Current behavior

Native device management has no generic way to discover and open a plugin-owned per-device settings page. Guessing an endpoint from a public device ID would couple native UI to plugin implementation details, while copying values into native storage would create two authorities.

Scoped proposal

• Add an optional settingsEndpoint declaration to a plugin driver.
• Require a safe endpoint identifier, an API permission, and a matching declared HTTP endpoint in the same manifest.
• Associate the endpoint with the registered driver/device instance rather than with a plugin-global mutable singleton.
• Open it through the existing in-app browser path with URL-encoded stable public deviceId and optional display name parameters.
• Check that the device is still loaded, eligible, and current before opening.
• Keep the plugin HTTP endpoint and the canonical existing kvStore authority as the sole persistence path; do not add a native duplicate store, migration, or ID-prefix inference.
• Keep plugin-global settings separate from per-device settings and preserve independent same-plugin instances.

Alternatives

A native mirror store would need synchronization and migration and would violate plugin ownership. Inferring an endpoint from plugin IDs breaks native fallback and representation changes. Adding a new host storage API is unnecessary because the existing namespaced kvStore endpoint already awaits writes and is exported. Opening arbitrary plugin URLs would bypass manifest and permission validation.

Proposed routing and open decisions

The draft's settingsEndpoint names a declared endpoint in the same plugin. The host builds /api/v1/plugins/:id/:endpoint with ui=1, exact public deviceId, and deviceName, and opens it using the existing url_launcher dependency. The plugin handles validation and storage.

1. Is settingsEndpoint on the driver the right place for this optional declaration?
2. Are those query parameters sufficient for per-device settings without adding a role-dependent identity?
3. Should this entry apply to both scales and sensors as implemented, and is the existing in-app browser/fallback behavior appropriate?

Related work

• feat(scale): add a manual USB-powered override for Skale #716, Skale USB per-device setting
• fix(scale): make Skale battery reporting nullable and refresh it #743 and feat(scale): add manual USB-powered override for Skale #745, retained metadata/settings boundary
• Generic device drivers through the JavaScript extension system #749, generic plugin boundary
• Plugin drivers: host-owned BLE binding + plugin-backed Scale support #809, closed host-owned plugin contract
• feat(plugins): add single-device Skale JS driver #846, Skale consumer
• feat(plugins): open per-device settings from device management #849, implementation draft

Acceptance criteria

• A declared settings endpoint is rejected unless its manifest permission and HTTP declaration both match.
• A valid device row opens the endpoint with correctly encoded stable identity and no token leakage.
• Plugin-global and per-device values remain independent for two same-plugin instances.
• Retired, unloaded, or stale devices cannot open settings.
• Settings writes use the existing canonical kvStore authority and survive reload/restart as specified.
• Native UI tests cover valid launch, malformed declaration, encoding, launch failure, and stale-device rejection.

Discussion status

This proposal is being opened alongside an existing draft implementation so the contract can be discussed explicitly. The draft is review material, not evidence of maintainer acceptance. Please settle the scope and API choices here before advancing it.

[tadelv]

Accepted for the 0.9.0 generic driver-runtime v2 track, with the generic boundary proposed here.

Decisions on the open points:

1. settingsEndpoint belongs on the driver/device declaration. It is optional and must resolve to a manifest-declared, permission-gated plugin HTTP endpoint.
2. deviceId is the required stable runtime identity. deviceName may be supplied as display-only convenience. Do not add connection-role or device-ID-prefix semantics to the settings contract.
3. This should be device-type agnostic, not hard-coded to scales/sensors. Any registered plugin-backed device type that declares a valid endpoint may use it; that includes the Grinder domain being defined in Define connected Grinder domain and API for generic driver runtime v2 #889. The existing in-app browser/fallback path is appropriate.

Keep the plugin endpoint + existing namespaced KV store as the sole persistence authority; no native mirror store.

This is useful to #889 specifically because vendor-only grinder controls can stay in plugin-owned settings instead of being promoted into the generic Grinder API. #849 can proceed on that basis.