@camstack/addon-export-google 0.1.1 → 0.1.3

package/dist/export-google.addon.mjs

@@ -11375,6 +11375,28 @@ method(object({}), object({ blocks: array(CoreBlockSchema) }), { auth: "admin" }
 	content: string()
 })) }), { auth: "admin" });
 /**
+* Identity — preserves literal types for downstream inference.
+*
+* The constraint is `Record<string, unknown>` (not `CustomActionsSpec`) so
+* TypeScript does not widen each entry's literal `kind`/`auth` fields to
+* the broader unions declared on `CustomActionSpec`'s default generics.
+* Shape validity is enforced separately by the `customAction(...)` helper
+* whose return type is already a `CustomActionSpec<...>`.
+*/
+function defineCustomActions(spec) {
+	return spec;
+}
+function customAction(input, output, options) {
+	return {
+		input,
+		output,
+		kind: options?.kind ?? "query",
+		auth: options?.auth ?? "protected",
+		scope: options?.scope ?? { kind: "system" },
+		...options?.caller ? { caller: "required" } : {}
+	};
+}
+/**
 * `custom-model-registry` — collection cap exposing operator-registered
 * custom detection models. Each provider (today: `addon-model-studio`)
 * contributes a list of `CustomModelDescriptor`s; the hub auto-concatenates
@@ -13443,6 +13465,114 @@ method(LogEntrySchema, _void(), { kind: "mutation" }), method(object({
 	limit: number().optional(),
 	tags: record(string(), string()).optional()
 }), array(LogEntrySchema).readonly());
+/**
+* `failure-contribution` — the capability an addon reports its OWN losses
+* through, per camera, with the denominator attached. It stores nothing.
+*
+* ## The twin of `load-contribution`, and why it is a twin and not a field
+*
+* `load-contribution` answers *what did this camera COST*. This answers *what
+* did this camera LOSE*. The reporting discipline is identical and deliberately
+* copied: the contributor reports what it already knows, hub-main adds only
+* `addonId`, nothing needs global knowledge, and there is no central list for
+* somebody to forget to edit.
+*
+* They are not merged, because their invariants are opposites:
+*
+*  - a `load-contribution` measurement is **absent, never zero** — a zero would
+*    claim a camera cost nothing, which is a measurement nobody made;
+*  - a `failure-contribution` zero is the **most valuable value on the
+*    surface** — `attempts: 400, succeeded: 400` is the proof a fix landed,
+*    and it is exactly what an absent entry cannot say.
+*
+* Putting a loss counter on a cost entry would also break the reconciliation
+* that gives `load-contribution` its point: contributions are subtracted from
+* `metrics.node-processes-snapshot` to find processes nobody claims. A failure
+* has no process.
+*
+* ## Why not a log line, since the counters already exist
+*
+* Several of these paths already counted themselves — `CaptureScheduler`'s
+* per-device window, `KeyFrameCaptureLog`, `bumpCropMetric`. Every one of them
+* ends in a log line, and a log line is the thing the operator asked to stop
+* needing: *"possiamo armare questi errori intanto? Così al prossimo giro
+* ricontrolliamo tutti questi punti"*. Reading them meant grepping Loki and
+* hand-correlating timestamps, which is how a 22% thumbnail gap and a 3-hour
+* media blackout were both diagnosed. The counters stay; this is where they can
+* be READ.
+*
+* ## The rate is served with its denominator or not at all
+*
+* Every entry carries `attempts` and `succeeded`. A miss count alone is
+* unreadable: on 2026-08-28 the enrichment-crop miss count read as "35x worse
+* than yesterday" and was **flat across twelve hours** once divided by the
+* successes on the same path. A surface that publishes only the numerator
+* reproduces that mistake on every read.
+*
+* ## Shape
+*
+* Copied from `load-contribution.cap.ts` (`mode: 'collection'`,
+* `internal: true`, `mount: { kind: 'skip' }`): no tRPC route of its own and no
+* generated hooks, while `addons.listCapabilityProviders` still enumerates it
+* and the hub's `CapabilityRegistry` still holds an RPC proxy per provider — so
+* a forked runner's entries reach hub-main over transport that already exists.
+* No new UDS message, no second registry (D3). The operator reads the assembled
+* result through `system.getFailureContributions`.
+*/
+var FailureReasonCountSchema = object({
+	/**
+	* Why the attempt did not land, in the contributor's own vocabulary —
+	* `worker-lease-gone`, `queue-overflow`, `timeout`, `empty-read`. The same
+	* strings that already appear in this repo's logs and, where one exists, the
+	* same string the per-track `previewMissReason` records (D276): a second
+	* vocabulary for the same loss would make the row and the counter
+	* un-joinable.
+	*/
+	reason: string(),
+	count: number().int().nonnegative()
+});
+var FailureContributionSchema = object({
+	/**
+	* The failing path — `enrichment-crop`, `inference`, `plate-ocr`,
+	* `person-over-vehicle`. Free text, for the reason `load-contribution` keeps
+	* `unit` free: the families are owned by different addons and a shared enum
+	* is a central list that rots invisibly.
+	*/
+	family: string(),
+	/**
+	* The NUMERIC device id — the same value every log line carries as
+	* `tags.deviceId`. Never nullable and never absent: a contributor that
+	* cannot name the camera must not emit the entry, because a fleet total
+	* cannot answer the only question anybody asks of this surface.
+	*/
+	deviceId: number().int().positive(),
+	/**
+	* A second dimension inside the family: the model / step id for an inference
+	* timeout, so "which camera AND which model" is one read. Absent when the
+	* family has a single variant.
+	*/
+	variant: string().optional(),
+	/**
+	* Epoch ms this counter started — the INCARNATION MARKER. A consumer
+	* differencing two reads must drop the interval when it changes, because the
+	* counter restarted from zero in a respawned runner. Same discipline as
+	* `LoadContribution.startedAtMs`.
+	*/
+	sinceMs: number(),
+	/** Epoch ms it was read. `atMs - sinceMs` is the interval this covers. */
+	atMs: number(),
+	/**
+	* THE DENOMINATOR — every attempt on this path for this camera in the
+	* window. A failure count published without it is the mistake this schema
+	* exists to make impossible.
+	*/
+	attempts: number().int().nonnegative(),
+	/** Attempts that landed. `attempts - succeeded` is the loss. */
+	succeeded: number().int().nonnegative(),
+	/** The loss, partitioned. Sums to `attempts - succeeded`. */
+	reasons: array(FailureReasonCountSchema).readonly()
+});
+method(_void(), array(FailureContributionSchema).readonly());
 var LoadContributionSchema = object({
 	role: _enum([
 		"decode",
@@ -17971,6 +18101,20 @@ var TrackSchema = object({
 	* `=== true` and render nothing otherwise — never infer "no rider".
 	*/
 	hasRider: boolean().optional(),
+	/**
+	* WHY this track ended without a NATIVE best-shot tile
+	* ([D276](../decisions/adr-0276-a-stand-in-tile-is-provisional-and-a-close-says-why.md)) —
+	* a composed token line (`no-key-frame capture=keyframe:native-missx4`,
+	* `derive-returned-null tile=standin`, …) written at close and CLEARED by
+	* the late-keyFrame upgrade when a native tile lands after all. The
+	* operator-facing answer to "perché manca l'immagine?" on a track whose
+	* tile is a face/plate stand-in, a raster crop, or an icon.
+	*
+	* **Absent ≠ "missed silently"**: a row written before the column, a hub
+	* that predates the field, and every track whose tile landed native all
+	* omit it. Render nothing when absent.
+	*/
+	previewMissReason: string().optional(),
 	...TrackFlagFields,
 	...TrackRetrainFields
 });
@@ -27216,6 +27360,13 @@ var LoggingSettingsPatchSchema = object({
 * anyone but its owner.
 */
 var ReportedLoadContributionSchema = LoadContributionSchema.extend({ addonId: string() });
+/**
+* One per-camera failure counter, plus WHO reported it.
+*
+* Same rule as {@link ReportedLoadContributionSchema}: `addonId` is stamped by
+* the hub as it enumerates providers, never by the contributor.
+*/
+var ReportedFailureContributionSchema = FailureContributionSchema.extend({ addonId: string() });
 var GetLoggingSettingsInputSchema = object({
 	scopeNodeId: string().optional(),
 	/**
@@ -27274,7 +27425,7 @@ method(_void(), FeatureManifestSchema), method(_void(), HealthStatusSchema), met
 }), method(_void(), SiteLocationStatusSchema, {
 	kind: "mutation",
 	auth: "admin"
-}), method(_void(), RequestCensusStatusSchema, { auth: "admin" }), method(_void(), array(ReportedLoadContributionSchema).readonly(), { auth: "admin" }), method(GetLoggingSettingsInputSchema, LoggingSettingsStateSchema, { auth: "admin" }), method(SetLoggingSettingsInputSchema, LoggingSettingsStateSchema, {
+}), method(_void(), RequestCensusStatusSchema, { auth: "admin" }), method(_void(), array(ReportedLoadContributionSchema).readonly(), { auth: "admin" }), method(_void(), array(ReportedFailureContributionSchema).readonly(), { auth: "admin" }), method(GetLoggingSettingsInputSchema, LoggingSettingsStateSchema, { auth: "admin" }), method(SetLoggingSettingsInputSchema, LoggingSettingsStateSchema, {
 	kind: "mutation",
 	auth: "admin"
 });
@@ -29856,6 +30007,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"failureContribution.list": {
+		capName: "failure-contribution",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"fanControl.setDirection": {
 		capName: "fan-control",
 		capScope: "device",
@@ -33162,6 +33319,12 @@ Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"system.getFailureContributions": {
+		capName: "system",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"system.getLoadContributions": {
 		capName: "system",
 		capScope: "system",
@@ -36049,6 +36212,32 @@ DEFAULT_NATIVE_LEASE_SETTINGS.admission;
 var MB = 1024 * 1024;
 1024 * MB, 3072 * MB;
 //#endregion
+//#region src/custom-actions.ts
+/**
+* Google Home export — customActions catalog.
+*
+* One entry. The settings form's `type: 'button'` field dispatches through the
+* generic `api.addons.custom.mutate({ addonId, action, input })` channel, so a
+* button here costs no capability, no codegen and no framework publish train —
+* the catalog travels inside this addon's own bundle.
+*/
+var exportGoogleActions = defineCustomActions({ 
+/**
+* Re-scan the connected `network-access` providers and refresh the address
+* shown under the field.
+*
+* Deliberately NOT the same contract as `export-alexa`'s action of the same
+* shape: that one replaces a manual override when it is no longer detected,
+* because Alexa ROUTES on the value. Nothing routes on this one — it is what
+* the operator already pasted into Google's console — so this only fills the
+* field when it is empty. `filled` says whether it did.
+*/
+detectPublicHubUrl: customAction(object({}).optional(), object({
+	publicHubUrl: string(),
+	detectedPublicHubUrl: string(),
+	filled: boolean()
+}), { kind: "mutation" }) });
+//#endregion
 //#region src/google-home/trait-catalog.ts
 /**
 * The trait catalog — one ROW per camstack capability, and that row is the
@@ -36077,7 +36266,7 @@ var MB = 1024 * 1024;
 * Cameras. Google's `CameraStream` trait answers `GetCameraStream` with a
 * playable URL or a WebRTC signaling endpoint, and neither exists here yet, so
 * a camera would be declared and then fail every command. It is omitted rather
-* than declared — see docs/decisions/adr-0268-one-capability-is-one-trait-row-that-declares-reads-and-writes.md.
+* than declared — see docs/decisions/adr-0273-one-capability-is-one-trait-row-that-declares-reads-and-writes.md.
 */
 /**
 * The Google state a SUCCEEDED call establishes.
@@ -36826,9 +37015,262 @@ function buildGoogleOauthIntegration() {
 	};
 }
 //#endregion
+//#region src/public-hub-url.ts
+/**
+* The hub's public HTTPS origin — detected, never invented.
+*
+* `publicHubUrl` is the single operator-facing value in this addon, and the
+* three URLs pasted into the Google Home Developer Console (fulfillment,
+* authorization, token) are all rendered from it. Nothing ROUTES on it: Google
+* calls the fulfillment URL it was configured with. A wrong value therefore
+* fails at paste time, in the console, hours before anything here notices —
+* which is exactly why the field has to say where its content came from.
+*
+* ## Where the URL comes from
+*
+* The `network-access` capability, same source `addon-export-alexa` uses. It is
+* a codegen'd collection cap with `scope: 'system'`, so it is reachable
+* cross-process through `ctx.api` — unlike the `addons` core router, which a
+* forked addon calling `ctx.api.addons.*` would wait on forever.
+*
+* **Not** `CAMSTACK_HUB_PUBLIC_URL`. That variable answers a different
+* question: which origin the hub should mint its OWN media / model-distribution
+* links on, and it defaults to `https://127.0.0.1:4443`. It is routinely a
+* loopback or LAN address, and the backend's `publicHubUrl()` fallback is
+* localhost in dev. Google calls from its own cloud, so a LAN answer here is
+* worse than no answer — it produces three console URLs that look complete and
+* can never be reached.
+*
+* ## Why this is a second copy of Alexa's mechanism
+*
+* Alexa's lives in `packages/addon-export-alexa/src/export-alexa.addon.ts` as
+* private methods, and addons never import each other. The only shared home
+* would be `@camstack/types` or `@camstack/system` — both stay host-resolved in
+* an addon bundle (`tools/build/vite-lib.preset.ts`), so putting it there would
+* put this addon on the framework publish train and destroy the one property
+* that makes it attractive: `camstack deploy packages/addon-export-google` and
+* nothing else. The SOURCE and the POLICY are Alexa's; two behaviours diverge
+* on purpose and both are named below.
+*
+* ## Two deliberate divergences from Alexa
+*
+* 1. **Refresh never clobbers.** Alexa's `redetectPublicHubUrl` replaces a
+*    manual override whenever it is not among the detected endpoints — sound
+*    there, because the URL is baked into every Alexa-bound JWT as a routing
+*    claim and a stale one breaks routing. Here the value is what the operator
+*    already pasted into Google's console; silently rewriting it would leave
+*    the console and the hub disagreeing with no visible cause. Detection fills
+*    an EMPTY field and does nothing else.
+* 2. **A non-routable origin is dropped.** Alexa forwards whatever the cap
+*    reports. See {@link isPubliclyRoutableOrigin}.
+*/
+/** Trailing slashes off, surrounding space off. Nothing else is rewritten. */
+var normalisePublicHubUrl = (raw) => raw.trim().replace(/\/+$/, "");
+var LOOPBACK_HOSTS = [
+	"localhost",
+	"127.0.0.1",
+	"::1",
+	"[::1]",
+	"0.0.0.0"
+];
+/**
+* Whether Google's cloud could plausibly reach this origin.
+*
+* The `network-access` providers this hub ships (Cloudflare Tunnel, Tailscale
+* Funnel) publish public FQDNs, but the cap does not promise it: a provider is
+* free to report an HTTPS ingress on a private address. Defaulting the field to
+* one of those would hand the operator three console URLs that look finished
+* and can never answer — strictly worse than an empty field, because an empty
+* field is visibly unfinished.
+*
+* Conservative on purpose: only loopback, RFC1918, link-local, `.local` and
+* dotless hostnames are refused. A public tunnel hostname always has a dot.
+*/
+var isPubliclyRoutableOrigin = (origin) => {
+	let host;
+	try {
+		host = new URL(origin).hostname.toLowerCase();
+	} catch {
+		return false;
+	}
+	if (host.length === 0) return false;
+	if (LOOPBACK_HOSTS.includes(host)) return false;
+	if (host.startsWith("127.") || host.startsWith("169.254.")) return false;
+	if (host.startsWith("10.") || host.startsWith("192.168.")) return false;
+	if (/^172\.(1[6-9]|2\d|3[01])\./.test(host)) return false;
+	if (host.endsWith(".local") || host.endsWith(".internal") || host.endsWith(".lan")) return false;
+	if (!host.includes(".")) return false;
+	return true;
+};
+/**
+* Every publicly routable HTTPS origin the `network-access` cap reports, in the
+* cap's own order, deduped. Empty when there is none — the caller leaves the
+* field alone rather than inventing a value.
+*/
+var detectPublicHubOrigins = async (deps) => {
+	const fromList = await originsFromListEndpoints(deps);
+	if (fromList.length > 0) return fromList;
+	const fromStatus = await originFromGetStatus(deps);
+	if (fromStatus.length > 0) return [fromStatus];
+	deps.logger.warn("export-google: no connected HTTPS external address — the public hub URL cannot be derived, so the Google console URLs stay unrendered. Set up remote access (Cloudflare Tunnel, Tailscale Funnel, …) and press \"Detect external address\", or type the URL on the settings form.");
+	return [];
+};
+var usableOrigins = (candidates, logger) => {
+	const out = /* @__PURE__ */ new Set();
+	for (const candidate of candidates) {
+		if (candidate.protocol !== "https" || candidate.url.length === 0) continue;
+		const origin = normalisePublicHubUrl(candidate.url);
+		if (!isPubliclyRoutableOrigin(origin)) {
+			logger.info("export-google: ignored an external address that is not reachable from the internet — Google calls the fulfillment URL from its own cloud", { meta: { origin } });
+			continue;
+		}
+		out.add(origin);
+	}
+	return [...out];
+};
+var originsFromListEndpoints = async (deps) => {
+	try {
+		return usableOrigins(await deps.network.listEndpoints(), deps.logger);
+	} catch (err) {
+		deps.logger.debug("export-google: networkAccess.listEndpoints failed", { meta: { error: errMsg(err) } });
+		return [];
+	}
+};
+var originFromGetStatus = async (deps) => {
+	try {
+		const status = await deps.network.getStatus();
+		if (status === null || !status.connected || status.endpoint === null) return "";
+		return usableOrigins([status.endpoint], deps.logger)[0] ?? "";
+	} catch (err) {
+		deps.logger.debug("export-google: networkAccess.getStatus failed", { meta: { error: errMsg(err) } });
+		return "";
+	}
+};
+/**
+* Apply the default-not-override policy.
+*
+* The operator's value is never in the returned patch. Detection's own answer
+* always is, because the settings panel needs it to say "you set this one, and
+* a different one is detected".
+*/
+var resolvePublicHubUrl = (current, detected) => {
+	const detectedPublicHubUrl = detected[0] ?? "";
+	if (current.length > 0) return {
+		patch: { detectedPublicHubUrl },
+		publicHubUrl: current,
+		detectedPublicHubUrl,
+		defaulted: false
+	};
+	if (detectedPublicHubUrl.length === 0) return {
+		patch: { detectedPublicHubUrl },
+		publicHubUrl: "",
+		detectedPublicHubUrl,
+		defaulted: false
+	};
+	return {
+		patch: {
+			publicHubUrl: detectedPublicHubUrl,
+			detectedPublicHubUrl
+		},
+		publicHubUrl: detectedPublicHubUrl,
+		detectedPublicHubUrl,
+		defaulted: true
+	};
+};
+/** Which of the two authored the value currently in the field. */
+var publicHubUrlSource = (state) => {
+	if (state.publicHubUrl.length === 0) return "unset";
+	if (state.detectedPublicHubUrl.length > 0 && state.publicHubUrl === state.detectedPublicHubUrl) return "derived";
+	return "operator-set";
+};
+/**
+* The line under the field. A URL that appeared by itself with no provenance is
+* worse than a blank field: the operator cannot tell whether it is right.
+*/
+var buildPublicHubUrlNotice = (state) => {
+	switch (publicHubUrlSource(state)) {
+		case "derived": return {
+			variant: "info",
+			content: `Derived from remote access — ${state.publicHubUrl} is the first HTTPS address the network-access capability reports. Edit the field to override it; nothing here ever overwrites a value you set.`
+		};
+		case "operator-set": return {
+			variant: "info",
+			content: state.detectedPublicHubUrl.length > 0 ? `Set by you — ${state.publicHubUrl}. The address currently detected from remote access is ${state.detectedPublicHubUrl}; paste it in yourself if you want to switch, detection will not do it for you.` : `Set by you — ${state.publicHubUrl}. No external HTTPS address is detected right now, so nothing is corroborating it.`
+		};
+		case "unset": return state.detectedPublicHubUrl.length > 0 ? {
+			variant: "info",
+			content: `Detected external address: ${state.detectedPublicHubUrl}. Press "Detect external address" to fill the field with it.`
+		} : {
+			variant: "warning",
+			content: "No public HTTPS address detected — no network-access provider on this hub reports a connected HTTPS endpoint, so there is nothing to derive from. Set up remote access (Cloudflare Tunnel, Tailscale Funnel, …) and press \"Detect external address\", or type the URL yourself. An address on your own network will not do: Google calls this URL from its own cloud."
+		};
+	}
+};
+/**
+* The `device-export` setup block: the three console URLs plus the
+* linked-account count. All three come off the SAME origin, so they can never
+* disagree with each other.
+*/
+var buildConsoleSetup = (input) => {
+	const origin = normalisePublicHubUrl(input.publicHubUrl);
+	const linked = String(input.linkedAccounts);
+	if (origin.length === 0) return {
+		note: ["Set the public hub URL on the settings form first — every URL Google needs is derived from it.", buildPublicHubUrlNotice(input).content].join("\n"),
+		fields: [{
+			label: "Linked Google accounts",
+			value: linked
+		}]
+	};
+	return {
+		note: [
+			"In the Google Home Developer Console create a cloud-to-cloud integration, then paste these three URLs.",
+			"The integration stays in test mode: publishing requires Google certification, which a private hub cannot obtain.",
+			"This hub pushes nothing to Google — state is read by polling, so a change made outside the Home app appears on the next query, not instantly.",
+			buildPublicHubUrlNotice(input).content
+		].join("\n"),
+		fields: [
+			{
+				label: "Fulfillment URL",
+				value: `${origin}/addon/${input.addonId}/fulfillment`
+			},
+			{
+				label: "Authorization URL",
+				value: `${origin}/api/oauth2/authorize?integration=${input.addonId}`
+			},
+			{
+				label: "Token URL",
+				value: `${origin}/api/oauth2/token`
+			},
+			{
+				label: "Linked Google accounts",
+				value: linked
+			}
+		]
+	};
+};
+/**
+* Detect, apply the policy, persist, and say out loud what happened.
+*
+* Every branch here logs: a fill names the URL it picked and the source it came
+* from, and a miss that leaves the field empty says so rather than passing for
+* "never ran".
+*/
+var refreshPublicHubUrl = async (deps) => {
+	const detected = await deps.detect();
+	const resolution = resolvePublicHubUrl(deps.current().publicHubUrl, detected);
+	await deps.persist(resolution.patch);
+	if (resolution.defaulted) deps.logger.info("export-google: defaulted public hub URL to the detected external address", { meta: {
+		publicHubUrl: resolution.publicHubUrl,
+		source: "network-access"
+	} });
+	else if (resolution.publicHubUrl.length === 0) deps.logger.warn("export-google: public hub URL still unset after detection — the Google console URLs cannot be rendered until one is available", { meta: { detectedCount: detected.length } });
+	return resolution;
+};
+//#endregion
 //#region src/types.ts
 var DEFAULT_SETTINGS = {
 	publicHubUrl: "",
+	detectedPublicHubUrl: "",
 	exposed: [],
 	linkedAccounts: []
 };
@@ -36867,7 +37309,7 @@ var DEFAULT_SETTINGS = {
 *
 * Switches, dimmable lights, locks and covers — the non-camera fleet neither
 * `export-hap` nor `export-alexa` covers. Cameras are out of scope on purpose
-* (docs/decisions/adr-0268-one-capability-is-one-trait-row-that-declares-reads-and-writes.md); the trait catalog is the single place that
+* (docs/decisions/adr-0273-one-capability-is-one-trait-row-that-declares-reads-and-writes.md); the trait catalog is the single place that
 * decides, so widening scope is one row.
 */
 var ADDON_ID = "export-google";
@@ -36882,6 +37324,9 @@ var ExportGoogleAddon = class extends BaseAddon {
 			logger: this.ctx.logger
 		});
 		this.gateway = gateway;
+		this.detectPublicHubUrl().catch((err) => {
+			this.ctx.logger.warn("export-google: public hub URL auto-detect failed", { meta: { error: errMsg(err) } });
+		});
 		const deviceExportProvider = {
 			getStatus: async () => ({
 				linkState: this.config.linkedAccounts.length > 0 ? "linked" : "unlinked",
@@ -36921,26 +37366,93 @@ var ExportGoogleAddon = class extends BaseAddon {
 			}
 		}));
 		const oauthIntegrationProvider = { getDescriptor: async () => buildGoogleOauthIntegration() };
+		const offTunnelStarted = this.ctx.eventBus.subscribe({ category: EventCategory.NetworkTunnelStarted }, () => {
+			this.detectPublicHubUrl().catch((err) => {
+				this.ctx.logger.warn("export-google: public hub URL detect after tunnel connect failed", { meta: { error: errMsg(err) } });
+			});
+		});
+		this.ctx.addDisposer(async () => offTunnelStarted());
 		this.ctx.logger.info("export-google: initialized", { meta: {
 			exposedCount: this.config.exposed.length,
 			linkedAccounts: this.config.linkedAccounts.length,
 			publicHubUrlSet: this.config.publicHubUrl.length > 0,
 			willReportState: false
 		} });
-		return { providers: [
-			{
-				capability: deviceExportCapability,
-				provider: deviceExportProvider
-			},
-			{
-				capability: addonRoutesCapability,
-				provider: routeProvider
+		return {
+			providers: [
+				{
+					capability: deviceExportCapability,
+					provider: deviceExportProvider
+				},
+				{
+					capability: addonRoutesCapability,
+					provider: routeProvider
+				},
+				{
+					capability: oauthIntegrationCapability,
+					provider: oauthIntegrationProvider
+				}
+			],
+			customActions: exportGoogleActions,
+			actionHandlers: { detectPublicHubUrl: async () => this.detectPublicHubUrl() }
+		};
+	}
+	/** This addon's slice of `PublicHubUrlState`. */
+	publicHubUrlState() {
+		return {
+			publicHubUrl: this.config.publicHubUrl,
+			detectedPublicHubUrl: this.config.detectedPublicHubUrl
+		};
+	}
+	/**
+	* Adapter from the codegen'd `network-access` router onto the narrow reader
+	* `public-hub-url.ts` consumes. Fields are copied one by one rather than
+	* passed through, so the module never depends on the cap's wider shape and a
+	* test double for it needs no cast.
+	*/
+	networkAccessReader() {
+		return {
+			listEndpoints: async () => {
+				return (await this.ctx.api.networkAccess.listEndpoints.query({})).map((entry) => ({
+					url: entry.url,
+					protocol: entry.protocol
+				}));
 			},
-			{
-				capability: oauthIntegrationCapability,
-				provider: oauthIntegrationProvider
+			getStatus: async () => {
+				const status = await this.ctx.api.networkAccess.getStatus.query({});
+				return {
+					connected: status.connected,
+					endpoint: status.endpoint === null ? null : {
+						url: status.endpoint.url,
+						protocol: status.endpoint.protocol
+					}
+				};
 			}
-		] };
+		};
+	}
+	/**
+	* Refresh the detected address and DEFAULT the field to it when it is empty.
+	* Backs both the boot-time detect and the "Detect external address" button.
+	*
+	* Never replaces a value the operator set — that value is what they already
+	* pasted into the Google console, and rewriting it here would leave the two
+	* sides disagreeing with nothing on screen to say so.
+	*/
+	async detectPublicHubUrl() {
+		const resolution = await refreshPublicHubUrl({
+			current: () => this.publicHubUrlState(),
+			detect: () => detectPublicHubOrigins({
+				network: this.networkAccessReader(),
+				logger: this.ctx.logger
+			}),
+			persist: (patch) => this.updateGlobalSettings(patch),
+			logger: this.ctx.logger
+		});
+		return {
+			publicHubUrl: resolution.publicHubUrl,
+			detectedPublicHubUrl: resolution.detectedPublicHubUrl,
+			filled: resolution.defaulted
+		};
 	}
 	async onShutdown() {
 		this.gateway = null;
@@ -37010,65 +37522,54 @@ var ExportGoogleAddon = class extends BaseAddon {
 	* tool for a real credential anyway (docs/decisions/adr-0269-a-google-export-that-holds-no-google-credential.md).
 	*/
 	buildSetupBlock() {
-		const origin = this.config.publicHubUrl.replace(/\/+$/, "");
-		const linked = this.config.linkedAccounts.length;
-		if (origin.length === 0) return {
-			note: "Set the public hub URL on the settings form first — every URL Google needs is derived from it.",
-			fields: [{
-				label: "Linked Google accounts",
-				value: String(linked)
-			}]
-		};
-		return {
-			note: [
-				"In the Google Home Developer Console create a cloud-to-cloud integration, then paste these three URLs.",
-				"The integration stays in test mode: publishing requires Google certification, which a private hub cannot obtain.",
-				"This hub pushes nothing to Google — state is read by polling, so a change made outside the Home app appears on the next query, not instantly."
-			].join("\n"),
+		return buildConsoleSetup({
+			addonId: ADDON_ID,
+			...this.publicHubUrlState(),
+			linkedAccounts: this.config.linkedAccounts.length
+		});
+	}
+	globalSettingsSchema() {
+		return this.schema({ sections: [{
+			id: ADDON_ID,
+			title: "Google Home export",
+			description: "Publishes switches, dimmable lights, locks and covers to Google Home. The hub answers Google directly — no cloud function, and no Google credential is stored here.",
+			columns: 1,
 			fields: [
 				{
-					label: "Fulfillment URL",
-					value: `${origin}/addon/${ADDON_ID}/fulfillment`
-				},
-				{
-					label: "Authorization URL",
-					value: `${origin}/api/oauth2/authorize?integration=${ADDON_ID}`
+					type: "info",
+					key: "__google-setup-banner",
+					label: "Setup overview",
+					variant: "info",
+					content: [
+						"This hub must be reachable from the public internet over HTTPS (Cloudflare Tunnel, Tailscale Funnel, …) — Google calls the fulfillment URL from its own cloud.",
+						"Create a cloud-to-cloud integration in the Google Home Developer Console, paste the three URLs from the Export panel, and link your account from the Home app.",
+						"Cameras are not exported, and state is not pushed: Google polls. Ask \"Hey Google, sync my devices\" after exposing something new."
+					].join("\n")
 				},
+				this.field({
+					type: "text",
+					key: "publicHubUrl",
+					label: "Public hub URL",
+					description: "HTTPS origin Google reaches this hub on, e.g. https://hub.example.com. Used to render the URLs you paste into the Google console. Left empty, it defaults to the first external address remote access reports; once it holds a value, nothing overwrites it.",
+					placeholder: "https://hub.example.com",
+					default: DEFAULT_SETTINGS.publicHubUrl
+				}),
 				{
-					label: "Token URL",
-					value: `${origin}/api/oauth2/token`
+					type: "info",
+					key: "__public-hub-url-source",
+					label: "Where this came from",
+					...buildPublicHubUrlNotice(this.publicHubUrlState())
 				},
 				{
-					label: "Linked Google accounts",
-					value: String(linked)
+					type: "button",
+					key: "__detect-public-hub-url",
+					label: "External address",
+					description: "Re-scan the connected remote-access providers. Fills the field above when it is empty; a value you set is left exactly as it is.",
+					buttonLabel: "Detect external address",
+					action: "detectPublicHubUrl",
+					variant: "default"
 				}
 			]
-		};
-	}
-	globalSettingsSchema() {
-		return this.schema({ sections: [{
-			id: ADDON_ID,
-			title: "Google Home export",
-			description: "Publishes switches, dimmable lights, locks and covers to Google Home. The hub answers Google directly — no cloud function, and no Google credential is stored here.",
-			columns: 1,
-			fields: [{
-				type: "info",
-				key: "__google-setup-banner",
-				label: "Setup overview",
-				variant: "info",
-				content: [
-					"This hub must be reachable from the public internet over HTTPS (Cloudflare Tunnel, Tailscale Funnel, …) — Google calls the fulfillment URL from its own cloud.",
-					"Create a cloud-to-cloud integration in the Google Home Developer Console, paste the three URLs from the Export panel, and link your account from the Home app.",
-					"Cameras are not exported, and state is not pushed: Google polls. Ask \"Hey Google, sync my devices\" after exposing something new."
-				].join("\n")
-			}, this.field({
-				type: "text",
-				key: "publicHubUrl",
-				label: "Public hub URL",
-				description: "HTTPS origin Google reaches this hub on, e.g. https://hub.example.com. Used to render the URLs you paste into the Google console.",
-				placeholder: "https://hub.example.com",
-				default: DEFAULT_SETTINGS.publicHubUrl
-			})]
 		}] });
 	}
 	/**