The production desktop uses native QML. Addon runtime behavior belongs in the
addon; its settings are presented by typed native adapters. main.ui, Designer
loaders, and the QWidget desktop are removed from the tested native checkout.
The old templates are reference material, not current
production scaffolds.
Choose a current reference
| Goal | Runtime reference | Presentation / contract reference |
|---|---|---|
| Chat provider | Claude entry point | Chat provider contract |
| Sensory source | Mock Heart Rate entry point | Small native adapter, source guide |
| Behavior for a source | Screen Supervisor entry point | Shared supervisor runtime, supervisor guide |
| Settings / actions | Hotkeys entry point | Hotkeys adapter |
| Visual Reply integration | Visual Reply entry point | Visual Reply guide |
| MCP consumer | YouTube Transcript entry point | MCP capability contract, user setup |
| TTS / avatar runtime | Closest first-party addon in addons/ |
Its matching adapter under ui/qml_bridge/adapters/ and existing runtime tests |
Start from the smallest relevant implementation. TTS, audio, avatar, model startup, Qt dispatch, and shutdown require their existing ownership/lifecycle patterns; a generic settings example does not establish a new runtime contract.
Manifest and lifecycle
Create addons/<name>/addon.json and main.py. A headless addon can start with:
{
"id": "nc.my_addon",
"name": "My Addon",
"category": "global",
"version": "0.1.0",
"entry_point": "main.py",
"description": "Short user-facing description.",
"permissions": [],
"enabled": true
}
Use a stable unique manifest ID, stable lowercase provider/source IDs, and addon-prefixed state keys. See manifest parsing and BaseAddon. The minimal entry point is still:
from core.addons.base import BaseAddon
class Addon(BaseAddon):
def initialize(self, context):
super().initialize(context)
context.logger.info("My addon initialized.")
def shutdown(self):
return None
This only initializes a headless addon. It does not create a settings page,
register a provider, or load a model. Register only the services the addon owns;
unregister them and stop owned work in shutdown().
The manager supplies an AddonContext, which exposes a generation-scoped
AddonHostContext through context.host and named ports through
context.capabilities. The implementation is in
context.py and
runtime/addons.py. Use those finite ports instead of
passing the main window, facade, backend or runtime context into addon calls.
Common named ports are providers, sensory_targets, runtime_config,
shell_session, hotkeys, and visual_reply. They can be unavailable; check
before use and follow the closest addon’s failure behavior. The older
context.get_service("qt.chat_providers") lookup still exists, but new examples
should follow the named port used by the current addon.
Permissions remain explicit:
| Permission | Addon-context operation |
|---|---|
ui.tabs |
Register a UI contribution identity |
storage.read / storage.write |
Read/write addon-owned files through context.storage |
events.subscribe / events.publish |
Use the addon event port |
services.register / services.consume |
Publish/consume peer services |
llm.read, tts.read, avatar.read |
Read the respective runtime snapshot |
For background work, inspect execution_lanes and owner-scoped task/process
handling in the boundary contract. Keep startup
light; do not introduce an unsupervised worker or a second model/audio runtime.
Add a native settings surface
Read these together:
- NativeControl / NativeSurface: immutable descriptions of control IDs, labels, sections, values, choices and metadata.
- NativeSurfaceAdapter / registry:
snapshot(),set_value(...),trigger(...), optionaltrigger_with_payload(...), and thechangedsignal. - AddonSessionNativeAdapter: a small
pattern for explicit
runtime.session.export/runtime.session.importcapabilities and a persistence callback. - Application bridge composition: where the shipped adapter instances are registered.
The manifest describes ownership and placement. For example, a native workspace
contribution uses this shape inside its ui list:
{
"id": "my_addon_tab",
"title": "My Addon",
"area": "top_level",
"order": 900,
"metadata": {"native_qml": true}
}
This metadata does not load an arbitrary adapter module automatically. The shipped native surfaces are explicitly composed in the application bridge. A new UI addon needs an actual adapter, registration in that composition, and routing to the intended workspace. Match the surface ID to the declared UI ID. Review that integration before assuming a third-party page will appear.
Keep snapshot() fast and free of generation, capture, network calls or model
loading. Use finite commands for mutations and keep enabled/busy/error state
truthful. NativeSurfaceRegistry dispatches actions according to their execution
metadata; inspect its implementation and the nearest action adapter before
choosing the UI or worker path.
register_designer_tab(...) now raises. The old
register_manifest_designer_tab(...) method has a compatibility path for native
metadata that registers contribution identity without constructing a Designer
file. That is not support for new .ui pages. Do not use the legacy widget
factories or edit main.ui to add a native addon.
State and secrets
Implement session and preset exports deliberately; do not copy session state wholesale into presets if it contains machine-specific values or credentials. Session restore and preset loading are different operations. Preserve existing keys and schemas; tolerate absent keys on import.
For a small preset-owned setting, the current notification port is:
self.context.capabilities.shell_session.notify_settings_changed()
Native adapters also receive persistence callbacks from the host. Keep their snapshot refresh, session save, and preset ownership consistent with the existing adapter; a legacy shell notification alone is not proof of persistence.
Use context.storage for addon-owned files and declare its permissions. Do not
export API keys, tokens, generated media, model weights, or cache paths into
portable presets. Follow state and presets and the
existing native session/secret policy instead of inventing a parallel writer.
Validate before sharing
From the repository root, run the relevant deterministic gates:
python tools/run_engine_decomposition_smokes.py --group addons
python ui/qml_bridge/smoke_native_qml_contract_coverage.py
python ui/qml_bridge/smoke_native_qml_no_legacy.py
The coverage gate checks declared native surfaces, adapters, controls and bindings. The no-legacy gate checks the removed widget paths and production imports. Passing documentation checks or one synthetic adapter test does not prove a provider, microphone, device, or model works.
Test enabled and disabled startup, setting edits, restart/restore, preset
round-trips where applicable, explicit errors, and shutdown. For providers, test
frozen normal-chat requests and cancellation; for audio/avatar code, use its
specific runtime checks. python qt_app.py launches the current desktop. The
old --validate-ui main.ui workflow belongs to the historical Designer migration.
