@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.
- package/dist/hub/admin-token-store.d.ts +53 -0
- package/dist/hub/admin-token-store.d.ts.map +1 -0
- package/dist/hub/admin-token-store.js +139 -0
- package/dist/hub/credentials.d.ts +53 -0
- package/dist/hub/credentials.d.ts.map +1 -0
- package/dist/hub/credentials.js +151 -0
- package/dist/hub/hub-address.d.ts +24 -0
- package/dist/hub/hub-address.d.ts.map +1 -0
- package/dist/hub/hub-address.js +87 -0
- package/dist/hub/hub-client.d.ts +57 -0
- package/dist/hub/hub-client.d.ts.map +1 -0
- package/dist/hub/hub-client.js +176 -0
- package/dist/hub/hub-tls.d.ts +16 -0
- package/dist/hub/hub-tls.d.ts.map +1 -0
- package/dist/hub/hub-tls.js +67 -0
- package/dist/hub/hub-url.d.ts +17 -0
- package/dist/hub/hub-url.d.ts.map +1 -0
- package/dist/hub/hub-url.js +54 -0
- package/dist/hub/session-store.d.ts +55 -0
- package/dist/hub/session-store.d.ts.map +1 -0
- package/dist/hub/session-store.js +178 -0
- package/dist/hub-discovery/hub-candidates.d.ts +53 -0
- package/dist/hub-discovery/hub-candidates.d.ts.map +1 -0
- package/dist/hub-discovery/hub-candidates.js +103 -0
- package/dist/hub-discovery/index.d.ts +4 -0
- package/dist/hub-discovery/index.d.ts.map +1 -0
- package/dist/hub-discovery/index.js +3 -0
- package/dist/hub-discovery/mdns-browse.d.ts +51 -0
- package/dist/hub-discovery/mdns-browse.d.ts.map +1 -0
- package/dist/hub-discovery/mdns-browse.js +116 -0
- package/dist/index.d.ts +15 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +11 -2
- package/dist/scaffold/addon.d.ts.map +1 -1
- package/dist/scaffold/addon.js +6 -0
- package/dist/types.d.ts +6 -1
- package/dist/types.d.ts.map +1 -1
- package/package.json +10 -1
- package/skills/README.md +3 -0
- package/skills/camstack-addon.md +376 -98
- package/skills/camstack-capability.md +184 -77
- package/skills/camstack-secrets.md +121 -34
package/skills/camstack-addon.md
CHANGED
|
@@ -1,9 +1,18 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: camstack-addon
|
|
3
|
-
description: Create or change a CamStack addon (plugin), or
|
|
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
|
-
#
|
|
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
|
-
- **
|
|
24
|
-
function without it on every node
|
|
25
|
-
|
|
26
|
-
|
|
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`
|
|
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
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
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
|
|
44
|
-
-
|
|
45
|
-
-
|
|
46
|
-
|
|
47
|
-
-
|
|
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
|
|
55
|
-
build, tests and
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
- **
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
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
|
|
73
|
-
| 3 | `src/index.ts` re-export |
|
|
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
|
-
`
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
`
|
|
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
|
|
94
|
-
npm run
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
112
|
-
`@camstack/server` install.
|
|
173
|
+
## 6. Documentation
|
|
113
174
|
|
|
114
|
-
|
|
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
|
-
|
|
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
|
-
|
|
126
|
-
|
|
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
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
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
|
-
##
|
|
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
|
-
|
|
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
|
-
|
|
155
|
-
|
|
156
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
166
|
-
|
|
167
|
-
|
|
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
|
+
```
|