feat: namespaced, runtime-toggleable trace channels (zero cost when disabled)

[fe-lix-]

Why

Three separate investigations this cycle (SITES-48958, the Universal Editor extension-loading-timeout work, and SITES-49454/RTE load) each hand-rolled the same throwaway instrumentation to see what Host.load()/Port.invokeHostMethod/Guest.invokeChecker were actually doing at runtime — an unconditional console.log, a flag re-checked per call, formatting done by hand at every call site. The formatting mistake (passing an object as a second console.log argument, which collapses to unreadable Array(N)/[{…}] placeholders in a plain-text devtools export) got made and re-fixed three separate times because there was nowhere for the lesson to live.

Each of those investigations also required vendoring a patched tarball into the consuming app just to get visibility — a multi-hour detour purely to answer "which guest is slow, and how long did it take."

What this adds

createTracer(namespace) in @adobe/uix-core (packages/uix-core/src/trace.ts):

• tracer.enabled is a live getter — a disabled tracer costs one function call + one property read + one typeof check. No string building, no object allocation, no JSON.stringify, ever, while disabled.
• details may be a plain object or a function returning one. Pass a function whenever building it costs more than a property read (mapping a guest list, serializing an error) — it's only invoked while the namespace is enabled.
• The tracer owns formatting (inline JSON.stringify, single log line, ISO timestamp) — a call site can no longer reintroduce the collapsing-object bug, because it never touches console.log directly.

window.__UIX_DEBUG__ — enable(pattern) / disable() / list() — lets anyone with devtools access turn tracing on after the fact, at runtime, without rebuilding or redeploying anything:

• Exact namespace ("uix-host"), trailing wildcard ("uix-*"), or "*" for everything.
• Persisted via ?uixDebug=... query param or localStorage["uix:debug"], so it survives a reload.
• Enabled-checks are evaluated live against the current pattern set, so enable("*") (or any pattern) also covers tracers created afterward — no dependency on module load order.

Wired into the three spots that needed ad-hoc vendoring to see previously:

• Host.addLoadsNewGuests/loadOneGuest (uix-host namespace): batch start/settle with the guest-id list, per-guest connect timing and outcome.
• Port.invokeHostMethod (uix-host namespace): every call, which host-api namespaces are currently registered for that guest, success/throw (including the async case via a non-blocking .then/.catch — behavior unchanged).
• Guest.invokeChecker (uix-guest namespace): the unbounded 500ms retry loop wrapping every guest→host call, with a per-call id and attempt counter.

Testing

• New packages/uix-core/src/trace.test.ts: namespace matching (exact/wildcard/*), disabled-by-default, details-thunk never called while disabled, enable()/disable()/list(), localStorage persistence across a simulated reload, retroactive enable of tracers created after enable("*").
• New packages/uix-host/src/host.test.ts (no host.test.ts existed on main before this): addLoadsNewGuests/loadOneGuest log batch start/settle and per-guest connect outcomes once uix-host is enabled, and log nothing otherwise (mocks Port entirely — real connection behavior stays covered by the existing port.test.ts).
• packages/uix-host/src/port.test.ts: new invokeHostMethod tracing block — logs the call plus currently-registered host-api namespaces, logs a throw when the requested namespace hasn't been provided yet (the exact signature that surfaced the Api.ts updateOn: "all" bug in the extension-loading investigation), and logs nothing while disabled.
• New packages/uix-guest/src/guest.test.ts, plus a uix-guest jest project in jest.config.ts (uix-guest had no wired-up unit tests on main at all before this): invokeChecker logs each attempt/success/failure with an incrementing attempt count and a callId held stable across the whole retry chain, and logs nothing while disabled.
• Every suite above explicitly asserts the disabled case emits zero console.log calls — the "no behavior/perf impact when off" claim is verified, not just documented.
• npx tsc --build clean across the whole monorepo.
• npx jest --selectProjects uix-core uix-host uix-guest — 65 passing, 0 failing, 13/13 suites.
• npx tsup builds uix-core, uix-host, and uix-guest clean; verified the tracing calls are present in each built dist/index.js.
• prettier --check clean on all touched files.

No behavior change when tracing is disabled (the default).

🤖 Generated with Claude Code