@camstack/develop 0.1.3 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. package/dist/hub/admin-token-store.d.ts +53 -0
  2. package/dist/hub/admin-token-store.d.ts.map +1 -0
  3. package/dist/hub/admin-token-store.js +139 -0
  4. package/dist/hub/credentials.d.ts +53 -0
  5. package/dist/hub/credentials.d.ts.map +1 -0
  6. package/dist/hub/credentials.js +151 -0
  7. package/dist/hub/hub-address.d.ts +24 -0
  8. package/dist/hub/hub-address.d.ts.map +1 -0
  9. package/dist/hub/hub-address.js +87 -0
  10. package/dist/hub/hub-client.d.ts +57 -0
  11. package/dist/hub/hub-client.d.ts.map +1 -0
  12. package/dist/hub/hub-client.js +176 -0
  13. package/dist/hub/hub-tls.d.ts +16 -0
  14. package/dist/hub/hub-tls.d.ts.map +1 -0
  15. package/dist/hub/hub-tls.js +67 -0
  16. package/dist/hub/hub-url.d.ts +17 -0
  17. package/dist/hub/hub-url.d.ts.map +1 -0
  18. package/dist/hub/hub-url.js +54 -0
  19. package/dist/hub/session-store.d.ts +55 -0
  20. package/dist/hub/session-store.d.ts.map +1 -0
  21. package/dist/hub/session-store.js +178 -0
  22. package/dist/hub-discovery/hub-candidates.d.ts +53 -0
  23. package/dist/hub-discovery/hub-candidates.d.ts.map +1 -0
  24. package/dist/hub-discovery/hub-candidates.js +103 -0
  25. package/dist/hub-discovery/index.d.ts +4 -0
  26. package/dist/hub-discovery/index.d.ts.map +1 -0
  27. package/dist/hub-discovery/index.js +3 -0
  28. package/dist/hub-discovery/mdns-browse.d.ts +51 -0
  29. package/dist/hub-discovery/mdns-browse.d.ts.map +1 -0
  30. package/dist/hub-discovery/mdns-browse.js +116 -0
  31. package/dist/index.d.ts +15 -2
  32. package/dist/index.d.ts.map +1 -1
  33. package/dist/index.js +11 -2
  34. package/dist/scaffold/addon.d.ts.map +1 -1
  35. package/dist/scaffold/addon.js +6 -0
  36. package/dist/types.d.ts +6 -1
  37. package/dist/types.d.ts.map +1 -1
  38. package/package.json +10 -1
  39. package/skills/README.md +3 -0
  40. package/skills/camstack-addon.md +376 -98
  41. package/skills/camstack-capability.md +184 -77
  42. package/skills/camstack-secrets.md +121 -34
@@ -1,9 +1,18 @@
1
1
  ---
2
2
  name: camstack-addon
3
- description: Create or change a CamStack addon (plugin), or extend a package with a new manifest entry. Covers the silent wiring misses, the runtime traps, deploy, and proving the new code is the code running.
3
+ description: Create or change a CamStack addon (plugin) — a device provider, notifier, storage or log destination, pipeline stage, exporter, a builtin, or any new `camstack.addons[]` manifest entry. Covers the silent wiring misses (vite entries, `super({})`), forked vs in-process behaviour, the two per-device settings stores, custom actions, device-page widgets, `camstack deploy` and its traps (installs, may not respawn, ships what is built), and how to prove the new code is the code running. Use for "new addon", "add a provider", "my addon change has no effect", "the addon is running but nothing happens".
4
4
  ---
5
5
 
6
- # Adding or extending an addon
6
+ # Creating or changing an addon
7
+
8
+ Written from doing it. Every step below exists because skipping it produced a
9
+ failure that compiled, passed tests, and broke at runtime or left the docs
10
+ lying. Long-form: `docs/architecture/addon-lifecycle.md` (processes, boot,
11
+ crashes) and `docs/architecture/addon-custom-actions.md`.
12
+
13
+ > Skill names with no file in this pack (`camstack-ui`, `camstack-ui-admin`,
14
+ > `camstack-server-change`, `camstack-diagnose`, `camstack-publish-ci`) are
15
+ > server-repository skills under `.claude/skills/`; this text stands on its own.
7
16
 
8
17
  ## Tooling (prefer this over hand-copying)
9
18
 
@@ -20,122 +29,220 @@ fails only at runtime.
20
29
 
21
30
  ## 1. Decide where it lives
22
31
 
23
- - **Builtin** (`packages/system/src/builtins/<name>/`) if the kernel cannot
24
- function without it on every node. Ships inside `@camstack/server`.
25
- - **Package** (`packages/addon-<name>/`) otherwise. Opt-in via install /
26
- `camstack deploy`.
32
+ - **A builtin** (`packages/system/src/builtins/<name>/`) if the kernel cannot
33
+ function without it, or it must exist on every node with no install step.
34
+ Builtins ship inside the `@camstack/server` closure.
35
+ - **Its own package** (`packages/addon-<name>/`) otherwise. Install is then the
36
+ opt-in, and it updates via `camstack deploy` independently of the framework.
27
37
 
28
- Read `docs/architecture/addon-lifecycle.md` in the server repo if unsure.
38
+ Read `docs/architecture/addon-lifecycle.md` first if you are unsure.
29
39
 
30
40
  ## 2. Write the addon
31
41
 
32
42
  ```
33
- packages/addon-<name>/
34
- package.json camstack.addons[]
35
- vite.config.ts entries map MUST include every addon entry
36
- src/<name>.addon.ts BaseAddon subclass
37
- src/index.ts
43
+ packages/<pkg>/src/<path>/
44
+ <name>.addon.ts the BaseAddon subclass
45
+ <name>-<thing>.ts the provider implementation
46
+ index.ts barrel, re-exporting the addon class
38
47
  __tests__/
39
48
  ```
40
49
 
41
50
  Rules that bite:
42
51
 
43
- - Providers on the logging path must not log into themselves.
44
- - Hot `write`-style methods must not throw (fan-out callers die with them).
45
- - Behavioural cap metadata (`kind`, `defaultActive`, `mode`) lives only in
46
- `*.cap.ts`, never the manifest.
47
- - Emit only through `ctx.eventBus` with `EventCategory`.
52
+ - **Providers must not log if they sit on the logging path.** A
53
+ `log-destination` that logs feeds itself. See `loki-destination.ts`.
54
+ - **`write`-style hot methods must not throw.** `LogManager` fans one entry to
55
+ every destination; throwing takes the siblings down.
56
+ - Keep behavioural capability metadata OUT of the manifest — it belongs in the
57
+ `*.cap.ts` (D4).
58
+ - Emit only through `ctx.eventBus` with the `EventCategory` enum
59
+ (D11).
48
60
  - Never `console.log` — use `ctx.logger`.
49
- - Never import another addon — use `ctx.api`.
50
61
 
51
- Rules that bite at RUNTIME, not at build time:
62
+ ### Rules that bite at RUNTIME, not at build time
52
63
 
53
64
  - **A `BaseAddon` subclass must call `super({})`** (or `super(defaults)`).
54
- Without it init throws `Cannot convert undefined or null to object` while
55
- build, tests and validation pass and the addon is listed as running.
56
- - **Declare a settings collection before querying it** (`declareCollection`
57
- in `init()`); the in-memory test store hides the miss.
58
- - **Device state in a forked addon can go stale** — reconcile
59
- `proxy.state.<cap>.value` with `refresh()` on a timer.
60
- - **Two per-device stores.** A forked addon reads `<addonId>:addon-devices`;
61
- write device config through the UI path (`applyDeviceSettingsPatch`).
62
- - **Bundle pure-JS dependencies** (`devDependencies`); runtime
63
- `dependencies` are for natives only.
64
- - **Credentials** are declared by schema type and never read from the
65
- environment — see the `camstack-secrets` skill.
66
-
67
- ## 3. Wire it — four places, one silent
68
-
69
- | # | Place | If you miss it |
65
+ Without it `resolveConfig` throws `Cannot convert undefined or null to
66
+ object` at init — build, tests and `check-addon-entries` all pass, the node
67
+ lists the addon as running, and the boot log says the builtin "failed to
68
+ initialize — skipping", sometimes followed by a misleading "Package
69
+ directory missing". Call one of its caps to prove it is alive.
70
+ - **`ctx.kernel.devices`** (create / register / remove / list) is on EVERY
71
+ addon, not only on `BaseDeviceProvider`. An addon that owns devices it
72
+ declares itself (an integration's panel, a synthetic device) reconciles them
73
+ with `DeclaredDevices` (`packages/types/src/device/declared-device.ts`) —
74
+ never a private `ensure…Device` (`scripts/check-declared-device-single-owner.ts`).
75
+ - **A settings collection is declared before it is queried.** The SQLite
76
+ backend refuses an undeclared collection (`declareCollection` in `init()`);
77
+ the in-memory test store auto-creates buckets and hides the miss, so pin the
78
+ path with a spec on the real backend.
79
+ - **Device state in a FORKED addon can go stale.** A `device.state-changed`
80
+ push does not reliably reach forked children, so a consumer of
81
+ `proxy.state.<cap>.value` reconciles with `refresh()` on a timer.
82
+ - **Device providers:** emit motion on every tick the camera reports, not only
83
+ on the rising edge — the pipeline's motion phase is keepalive-driven and
84
+ expires without it. Write the cap slice on the edge only.
85
+ - **Two per-device settings stores.** A forked addon reads its per-device
86
+ config from `<addonId>:addon-devices` (one blob per device);
87
+ `addonSettingsRaw.updateDevice` writes a DIFFERENT table. The UI path
88
+ (`applyDeviceSettingsPatch`) is right. A script fixing one device writes
89
+ `settingsBackend.set {collection:"<addonId>:addon-devices", key, value}`,
90
+ which REPLACES the blob — read it with `settingsBackend.query` and merge first.
91
+ - **Bundle pure-JS dependencies** (put them in `devDependencies`); runtime
92
+ `dependencies` are for true natives only, because the installer runs
93
+ `npm install` on a node only when runtime dependencies remain.
94
+ - **A forked addon serving its own HTTP** goes through the hub's
95
+ `/addon/:addonId/*` bridge, which does not compress (`server/backend/src/main.ts`);
96
+ own the encoding end to end and never add compression to a byte-stream route.
97
+ - **Secrets** — any password, token or key field, `secretStatePaths`, a
98
+ credential for a spawned child: the `camstack-secrets` skill. Never read a
99
+ credential from the environment.
100
+
101
+ ## 3. Wire it — the four places, one of which is silent
102
+
103
+ | # | Place | What happens if you miss it |
70
104
  | --- | --- | --- |
71
- | 1 | `camstack.addons[]` in package.json | addon does not exist |
72
- | 2 | **`vite.config.ts` `entries` map** | compiles, fails at runtime |
73
- | 3 | `src/index.ts` re-export | hard to import / test |
105
+ | 1 | `camstack.addons[]` in the package's `package.json` | the addon does not exist |
106
+ | 2 | **`vite.config.ts` `entries` map** | **everything compiles and the addon fails at runtime** |
107
+ | 3 | `src/index.ts` re-export | consumers and tests cannot import it |
74
108
  | 4 | `packages/system/src/index.ts` (builtins only) | same |
75
109
 
76
- `description` is required in practice — Admin UI and generated docs show `—`
77
- without it. Manifest fields: `execution.placement`, `execution.group`,
78
- `instanceMode`, `storageLocations`, `icon` / `color`, `protected`.
79
-
80
- ## 4. Opt-in (no manifest `enabled` flag)
81
-
82
- Every declared addon loads. Prefer config-default inertness (`enabled: false` +
83
- empty required field) and still register the provider so the UI can turn it on.
84
- Alternatively: a separate npm package (install = opt-in), or
85
- `addons.setCapabilityProviderEnabled` for collection caps.
110
+ Number 2 is the one. A manifest `entry` is just a string — nothing resolves it at
111
+ build time. `scripts/check-addon-entries.ts` now catches it; run it.
112
+
113
+ Manifest fields worth knowing: `protected: true` blocks uninstall ·
114
+ `execution.placement: 'agent-only' | 'any-node'` (default `hub-only`) ·
115
+ `execution.group` co-locates into one process (D2)
116
+ · `instanceMode` · `storageLocations` · `icon` / `color`.
117
+
118
+ **`icon` is a promise the hub must keep.** It is an asset PATH inside the
119
+ package (`assets/icon.svg`, or `assets/<addonId>/icon.svg` when one package ships
120
+ several addons — `@camstack/system` does this for every builtin), and the folder
121
+ must be in `files` or `npm pack` drops it. The Admin UI requests
122
+ `/api/addon-assets/<addonId>/<icon>` only for an addon that declares one
123
+ (`addon-admin-ui/src/lib/addon-icons.ts`); everything else draws a glyph with no
124
+ request, so never build that URL by hand or guess an id. House style: 24-unit
125
+ `viewBox`, no fill, `stroke-width="2"`, round caps/joins, a fixed stroke colour
126
+ (the `<img>` cannot inherit `currentColor`), legible at 16 px.
127
+ `scripts/check-addon-icons-shipped.ts` fails CI on a declared icon that is
128
+ missing or unshipped.
129
+
130
+ **`description` is not optional in practice** — it is what
131
+ `docs/reference/addons.md` and the Admin UI show. An addon with no description
132
+ documents itself as `—`.
133
+
134
+ ## 4. Opt-in, if it should be off by default
135
+
136
+ There is **no `enabled` flag on a manifest**, and **no `enabled` setting in an
137
+ addon's own config either** (D777): the capability toggle is the ONE enable. A
138
+ private "master switch" is a second truth that can say "off" while the toggle
139
+ says "on". The scaffolds do not generate one; do not add one. The real
140
+ mechanisms:
141
+
142
+ 1. **Config-default inertness** — an empty required field (a URL, a token) in
143
+ the addon's own settings, which the provider treats as inert. Register the
144
+ provider anyway, so the UI can show it and the operator can configure it.
145
+ This is what `loki-logging` does.
146
+ 2. **Capability toggle** — `addons.setCapabilityProviderEnabled({ capName,
147
+ addonId, enabled })`, the Enable/Disable control the UI already shows.
148
+ Collection caps only; persisted **globally** under
149
+ `capabilities.collection.<cap>`, not per node. It refuses a provider that is
150
+ not registered yet, so never call it from `onInitialize` (the providers it
151
+ returns register only after it returns) — retry in the background, as
152
+ `loki-logging/retire-enabled-flag.ts` does.
153
+ 3. **A separate npm package** — installing it is the opt-in.
154
+
155
+ Prefer 1 for "needs configuring first", and 2 for an on/off choice.
86
156
 
87
157
  ## 5. Verify
88
158
 
89
159
  ```bash
90
160
  npm run codegen # only if you touched a *.cap.ts
91
- camstack develop validate <pkg>
92
161
  npx tsx scripts/check-addon-entries.ts
93
- npm run typecheck -w packages/addon-<name>
94
- npm run build -w packages/addon-<name> && ls packages/addon-<name>/dist/
162
+ npm run typecheck && npm run test # typecheck = code + specs vs the pinned debt (D695)
163
+ npm run typecheck -w packages/<pkg> # your package raw: a NEW addon has no pinned debt, so it must be clean
164
+ npm run docs:check
95
165
  ```
96
166
 
97
- ## 6. Documentation
98
-
99
- Generated on commit: `docs/reference/{addons,packages,capabilities,…}.md` —
100
- do not hand-edit. You write: `docs/history/sessions.md`, a decision record when
101
- you rejected a real alternative, architecture prose only when a whole subsystem
102
- changed. Run `npm run docs:check`. Use the `camstack-docs` skill.
103
-
104
- ## 7. Ship
167
+ Then **actually build it** and confirm the entry was emitted:
105
168
 
106
169
  ```bash
107
- camstack deploy packages/addon-<name>
108
- camstack deploy packages/addon-<name> -n <nodeId>
170
+ npm run build -w packages/<pkg> && ls packages/<pkg>/dist/<path>/
109
171
  ```
110
172
 
111
- Local `dist/` has **no runtime effect** until deploy. Builtins need a
112
- `@camstack/server` install.
173
+ ## 6. Documentation
113
174
 
114
- Deploy traps:
175
+ `docs/reference/{addons,packages,capabilities,guards}.md` regenerate from the
176
+ manifests on commit — do not describe your addon in prose a table covers. The
177
+ rest (sessions entry, an ADR for a rejected alternative, a package
178
+ `AGENTS.md` for traps a future session will hit — see
179
+ `docs/addons/addon-provider-reolink.md`) follows the `camstack-docs`
180
+ ladder. `npm run docs:check` fails on a dead path.
115
181
 
116
- - `deploy` **installs** a package that is not on the target — a second
117
- provider on a singleton can break a working one. Check first.
118
- - It ships what is **built** in that package, committed or not.
119
- - It may not respawn the runner: confirm a fresh process, or call
120
- `addons.restartAddon({ addonId })`.
121
- - After deploying a multi-entry package, check every cap it provides still has
122
- a provider (`capabilities.getCapability`).
123
- - The post-deploy health probe races the restart — use `--no-verify` and poll.
182
+ ## 7. Ship it — and prove the new code is the code running
124
183
 
125
- **Proof the change is live:** grep the deployed bundle for a string new in this
126
- build, then exercise the behaviour (call the cap, watch the new log line).
184
+ An addon runs from its DEPLOYED copy under `<dataDir>/addons/@camstack/<name>/`
185
+ (in a workspace dev hub, the data dir under `server/backend`), never from
186
+ `packages/<name>/dist`. Editing and rebuilding has **no runtime effect** until
187
+ you deploy. A **builtin** travels inside `@camstack/server` instead — the
188
+ `camstack-server-change` skill (D16).
127
189
 
128
- ## Done-gate
129
-
130
- ```
131
- ADDON DONE — <addonId>
132
- wiring: manifest + vite entries + index re-export; check-addon-entries ok
133
- checks: typecheck / tests / build emitted <dist path>
134
- deployed: <nodes> — fresh runner; caps registered
135
- proved: <the call / log line observed>
136
- docs: <files | none needed: reason>
190
+ ```bash
191
+ camstack deploy packages/addon-<name> # to the hub; or: camstack deploy <name>
192
+ camstack deploy packages/addon-<name> -n <nodeId> # to one agent — one node at a time
193
+ camstack deploy packages/addon-<name> --no-verify # then poll /health yourself (below)
137
194
  ```
138
195
 
196
+ Auth comes from `camstack login` (cached per server) or `--token` /
197
+ `--token-file` / `$CAMSTACK_TOKEN`; `-s <url>` names the hub. Full reference:
198
+ `docs/architecture/update-and-release.md` §"Deploying an addon during
199
+ development", which also has the stale-addon detector to run after a rebase.
200
+
201
+ Traps, each of which has cost a session:
202
+
203
+ - **`deploy` INSTALLS, it does not only update.** Deploying a package that is
204
+ not installed on the target hot-loads it — a second provider on a singleton
205
+ can break a working one. Check the target's addons first
206
+ (`nodes.getNodeAddons`; `addons.list` can be a stale cache).
207
+ - **It ships what is BUILT in that package, committed or not** — including
208
+ another agent's work in the same tree. "Do not deploy" in one brief does not
209
+ stop a sibling from deploying the same package; keep must-not-ship changes
210
+ out of the built tree.
211
+ - **It may not respawn the runner.** The new dist can land while the old
212
+ module keeps running. Confirm a fresh process (a new PID / boot line for the
213
+ addon) or call `addons.restartAddon({ addonId })`.
214
+ - **A multi-manifest package may come back partly unregistered.** After the
215
+ deploy, check `capabilities.listCapabilities` (or `getCapability`) for every
216
+ cap the package provides; a cap with no provider → `addons.restartAddon`.
217
+ - **The post-deploy health probe races the restart** and reports
218
+ `1/1 target(s) failed` after a successful install — use `--no-verify` and
219
+ poll `/health` yourself.
220
+ - **`-n <nodeId>` accepts an id that does not exist** and still prints
221
+ `✓ Deployed`. Verify on the node. `nodes.deployAddon` does not ship bundles —
222
+ the CLI's `-n` is the channel.
223
+ - **Agents run their own copy.** A hub deploy does not update an agent's copy
224
+ of a hub-only addon, and enabling a feature on a node whose code lacks it
225
+ shows as "Cannot register provider for undeclared capability" — version
226
+ skew, roll the enablement back.
227
+ - **Repeated rapid deploys of media addons** (stream broker, providers)
228
+ degrade the hub. One deploy, then verify; a restart only if needed.
229
+ - **The hub auto-updater** applies newly published npm versions on its
230
+ schedule and can replace a CLI-deployed build whose version differs; deploy
231
+ after the version-bump commit, and check `addons.setAddonAutoUpdate` for
232
+ framework packages.
233
+ - **admin-ui** deploys need no hub restart, but a browser keeps the old PWA
234
+ bundle until a hard reload; a blank page with a "MIME type text/html" module
235
+ error is a stale service worker.
236
+ - **Never hand-edit the node's addon manifest** (`<dataDir>/addons/manifest.json`):
237
+ an entry whose directory is gone kills the runner and everything co-located.
238
+ "Required and cannot be uninstalled" comes from `protected: true` in the
239
+ installed `package.json`.
240
+
241
+ **Proof the change is live**: grep the deployed bundle for a string that is
242
+ new in this build, then exercise the behaviour (call the cap, press the
243
+ button, watch the new log line) — the `camstack-diagnose` skill. A deployed
244
+ bundle is not the running code until the process restarted.
245
+
139
246
  ## Extending (second entry in one package)
140
247
 
141
248
  Multi-entry packages (auth, cloudflare, …) need a new id, source file, manifest
@@ -145,23 +252,194 @@ row, **and** vite `entries` key. Prefer:
145
252
  camstack develop extend <package> --entry <new-id>
146
253
  ```
147
254
 
148
- ## Device-page widgets
255
+ ## Operator buttons (custom actions)
256
+
257
+ An addon-owned RPC on the `addons.custom` bridge, rendered by the settings form
258
+ as a button — no bespoke admin page. Read
259
+ `docs/architecture/addon-custom-actions.md`
260
+ BEFORE adding one.
261
+
262
+ The trap it exists to prevent: there are **two** registration paths, and which
263
+ one applies depends on whether the addon runs in-process or forked — which is
264
+ not a property of the source. Populate BOTH the `customActions` named export of
265
+ the entry module AND the `customActions` returned by `onInitialize`, or the
266
+ bridge answers 404 with your code visibly present in the built bundle.
267
+
268
+ ## A UI surface on a DEVICE page (widgets)
269
+
270
+ Your addon has an editor, a panel, a canvas — richer than a form — and it
271
+ belongs on the camera's own page. Read this before writing any of it, because
272
+ one of the available mechanisms **silently does nothing**, and choosing between
273
+ the other two is a judgement call with a rule
274
+ (D526).
275
+
276
+ ### What the device page actually asks
277
+
278
+ `getDeviceSettingsAggregate` is **binding-driven** (`device-aggregation.ts`,
279
+ D12): it walks the `(cap, provider)`
280
+ pairs bound to THIS device and asks each. Cap names are shared across vendors
281
+ and a device belongs to exactly one integration, so a contribution may only come
282
+ from a provider bound to it. For each binding it either derives the section from
283
+ a `deviceConfig` cap (D14) or, when the
284
+ cap sets `exposesDeviceSettings`, asks the provider —
285
+ `registry.getProviderByAddon(capName, entry.providerAddonId)`, the ADDON's
286
+ provider, never the per-device native.
287
+
288
+ **There is no addon-level route into that page.** That is deliberate, not an
289
+ omission.
290
+
291
+ ### The trap
292
+
293
+ Declaring a `type: 'widget'` field in your addon's `deviceSettingsSchema()`
294
+ looks right and is valid everywhere you can check it: the hub returns the
295
+ section, `ConfigFormField` renders `type:'widget'` via `WidgetField`, your
296
+ component is in the shipped bundle. **Nothing appears**, because that method
297
+ feeds only **Cluster → Pipeline → Device Overrides**, whose addon set is a
298
+ hand-written list:
299
+
300
+ ```ts
301
+ // packages/addon-admin-ui/src/components/pipeline/pipeline-panel-addons.ts
302
+ export const PIPELINE_CLUSTER_DEVICE_ADDONS = [
303
+ 'pipeline-orchestrator', 'motion-wasm', 'audio-analyzer', 'detection-pipeline',
304
+ ] as const
305
+ ```
306
+
307
+ Its own comment says addons not on it "fall off silently". **That list is a
308
+ defect** — an addon declaring a valid schema is ignored with no log line — but
309
+ adding yours is still the wrong fix: that page is for per-camera detection
310
+ tuning, not for your feature.
149
311
 
150
- There is no addon-level route onto a camera settings page. Sections come from
151
- capabilities bound to the device. Ask: would another vendor implement this cap
152
- unchanged?
312
+ ### Pick by ownership, not by example
153
313
 
154
- - **Yes (generic)** — `deviceConfig.ui.kind: 'widget'` and register the host
155
- widget. Framework derives the section.
156
- - **No (owned)** — cap sets `exposesDeviceSettings: true`; provider returns a
157
- hydrated `ConfigUISchema`.
314
+ Both real mechanisms hang the widget off a **capability** bound to the device.
315
+ Which one you use is decided by ONE question, and it is not "which did I see
316
+ first" — neither is canonical:
158
317
 
159
- Do not put `type: 'widget'` only in an addon's `deviceSettingsSchema()` hoping
160
- the device page picks it up — that path feeds a different Admin surface and can
161
- silently show nothing.
318
+ > **Would another vendor implement this capability, without changing it?**
162
319
 
163
- ## Custom actions (operator buttons)
320
+ - **Yes — the cap is GENERIC.** Let the framework derive the section. Any other
321
+ answer means the same section gets hand-written once per vendor and diverges
322
+ at the first edit.
323
+ - **No — the cap is OWNED**, meaning one addon implements it *and* that addon
324
+ owns the device. Declare the section yourself.
164
325
 
165
- Populate **both** the entry module's `customActions` export and
166
- `onInitialize`'s `customActions`, or the bridge 404s depending on in-process vs
167
- forked. See `docs/architecture/addon-custom-actions.md`.
326
+ Answer it about the capability, not about today's fleet. A cap with one
327
+ implementer right now can still be generic: `navigation` and `consumables` are
328
+ dreame-only today and another robot vendor would implement either untouched, so
329
+ both are generic. `consumables` says so in its own definition — `status.empty`
330
+ plus `status.itemArray` make it a device-link synthesize target, so it can
331
+ appear on a device no dreame provider owns at all.
332
+
333
+ ### A GENERIC cap — the framework derives the section
334
+
335
+ ```ts
336
+ deviceConfig: {
337
+ ui: { kind: 'widget', widgetId: 'host/your-widget', tab: 'streaming', label: '…' },
338
+ }
339
+ ```
340
+
341
+ The framework emits the structural section out of the binding entry — **no
342
+ provider call, so it cannot fail** — and the widget self-persists through the
343
+ cap's own mutations. `motion-zones`, `privacy-mask`, `ptz`, `ptz-autotrack`,
344
+ `navigation` and `consumables` all do this, and all six are correct. Register
345
+ the component in `HOST_WIDGETS`
346
+ (`packages/ui-library/src/widgets/host-widgets.ts`).
347
+
348
+ **Weigh the cost honestly before minting a cap for this.** A new cap is a
349
+ framework change: `npm run codegen`, the two hand-edits in
350
+ `packages/types/src/capabilities/index.ts`, and it reaches a node only inside a
351
+ published `@camstack/server` (D16).
352
+ `camstack deploy <your-addon>` will NOT make the widget appear, and neither will
353
+ deploying `admin-ui` — the cap carrying the section does not exist there yet.
354
+
355
+ ### An OWNED cap — your addon returns the section
356
+
357
+ The cap sets `exposesDeviceSettings: true` and the provider RETURNS a
358
+ `ConfigUISchema` containing the widget field. `recording`
359
+ (`recorder/recording-device-settings.ts`) and `camera-grid-layout`
360
+ (`system/src/builtins/camera-grid/grid-layout-native-provider.ts`, section built in
361
+ `grid-device-settings.ts`) are the two:
362
+
363
+ ```ts
364
+ sections: [{ id: '…', tab: 'recording', location: 'top-tab', order: 10,
365
+ fields: [{ type: 'widget', widgetId: 'host/recording-panel' }] }]
366
+ ```
367
+
368
+ What that buys, and nothing else does: the ADDON picks the section, tab,
369
+ location and order, and it can decline PER DEVICE — `recording` returns `null`
370
+ for anything that is not a camera, so the tab never appears there.
371
+
372
+ `recording` is also the example worth remembering, because it LOOKS generic and
373
+ is not: "record this camera" sounds like something several addons could offer,
374
+ and only the recorder ever does.
375
+
376
+ Three things bite here:
377
+
378
+ - **Return the WIRE shape.** Run your schema through `hydrateSchema(schema, {})`
379
+ — a widget stores no values, but the aggregation expects the hydrated form.
380
+ - **A `deviceNative` cap needs the contribution on BOTH providers — one
381
+ builder, two registrations.** There are two paths and they reach different
382
+ objects:
383
+ - the DEVICE PAGE resolves with
384
+ `registry.getProviderByAddon(capName, entry.providerAddonId)`
385
+ (`device-aggregation.ts`), which reads the ADDON-level provider map only.
386
+ No addon-level provider ⇒ the section is dropped and **nothing is logged**.
387
+ - a DIRECT cap call carries a `deviceId`, so `child-cap-dispatch` answers it
388
+ from the DEVICE-scoped provider and THROWS when the method is missing there
389
+ (the singleton fallback exists only for a collection cap's list method).
390
+
391
+ Both were measured on the live hub on 2026-09-17, one after the other: the
392
+ wrapper alone gave HTTP 500 on the direct call; the native alone gave a device
393
+ aggregate of 30 sections with ours absent and no error anywhere. Build the
394
+ provider ONCE in a factory and register it twice — as the native
395
+ (`registerNativeCap`, typed `InferProvider`, which a native registration
396
+ happily accepts as a superset) and as the addon's own provider from
397
+ `onInitialize`. Worked example:
398
+ `packages/system/src/builtins/camera-grid/grid-layout-native-provider.ts`.
399
+ `getDeviceSettingsContribution` must return the WIRE shape — run the schema
400
+ through `hydrateSchema(schema, {})`; a widget stores no values.
401
+ - **`deviceConfig` and `exposesDeviceSettings` are mutually exclusive**
402
+ (`capability-definition.ts`). Remove one as you add the other.
403
+
404
+ **Neither shape avoids the capability.** `exposesDeviceSettings` on a cap you do
405
+ not own is not an option: the caps a device-owning addon typically already has
406
+ bound (`device-status`, `feature-probe`, `stream-catalog`, `device-ops`) are
407
+ SHARED across dozens of providers, and flipping that flag makes the aggregation
408
+ call `getDeviceSettingsContribution` on every one of them. Fleet-wide blast
409
+ radius to render one panel.
410
+
411
+ Two more that bite either way:
412
+
413
+ - **`topTab: true` needs a known tab.** A `topTab` widget must name a tab in
414
+ `WELL_KNOWN_TAB_MAP` (`packages/types/src/interfaces/config-ui.ts`) or the UI
415
+ renders the raw tab id as the label. Use an existing tab unless you also add
416
+ the entry — and note that the tab's label, icon and position in the bar are a
417
+ `@camstack/types` constant, so they are a framework publish whichever
418
+ mechanism declares the section.
419
+ - **If the addon owns the device, make the cap `deviceNative`** and register it
420
+ from the device class, so the widget asks *the camera* through the ordinary
421
+ device proxy.
422
+
423
+ ### Diagnosing which failure you have
424
+
425
+ ```bash
426
+ node scripts/hub/hub.mjs GET addonSettings.getDeviceSettings '{"addonId":"…","deviceId":N}'
427
+ node scripts/hub/hub.mjs GET deviceManager.getBindings '{"deviceId":N}'
428
+ ```
429
+
430
+ If the first returns your section and the second does not list your cap, the
431
+ data is fine and **nobody is asking** — you are on the wrong mechanism. Grepping
432
+ the deployed bundle for your widget id proves only that the code shipped; it
433
+ says nothing about whether anything requests it. On the day this was diagnosed,
434
+ three checks out of four said "fine"; only "who ASKS" told the truth.
435
+
436
+ ## Done-gate
437
+
438
+ ```
439
+ ADDON DONE — <addonId>
440
+ wiring: manifest + vite entries + index re-export; check-addon-entries ok
441
+ checks: typecheck / tests / build emitted <dist path>
442
+ deployed: <nodes> — fresh runner; caps registered
443
+ proved: <the call / log line observed>
444
+ docs: <files | none needed: reason>
445
+ ```