@camstack/system 1.2.116 → 1.2.118

package/dist/{dist-Cri60Jd0.js → dist-C2_1HCpW.js}

@@ -4123,6 +4123,15 @@ var LabelDefinitionSchema = zod.z.object({
 	description: zod.z.string().optional(),
 	icon: zod.z.string().optional()
 });
+var ClassMapDefinitionSchema = zod.z.object({
+	mapping: zod.z.record(zod.z.string(), zod.z.enum([
+		"person",
+		"vehicle",
+		"animal",
+		"package"
+	])),
+	preserveOriginal: zod.z.boolean()
+});
 var MODEL_FORMATS = [
 	"onnx",
 	"coreml",
@@ -4301,7 +4310,13 @@ var ModelCatalogEntrySchema = zod.z.object({
 	* `id` stays the source of truth for resolution/download/persistence; grouping
 	* is a presentation overlay resolved back to an `id`.
 	*/
-	group: ModelVariantGroupSchema.optional()
+	group: ModelVariantGroupSchema.optional(),
+	/**
+	* Per-MODEL class map override. Absent ⇒ the step's `StepDefinition.classMap`
+	* applies (Frigate / COCO public catalog). Set on a custom model whose raw
+	* labels already ARE the CamStack macros (Scrypted identity map).
+	*/
+	classMap: ClassMapDefinitionSchema.optional()
 });
 var ConvertTargetSchema = zod.z.discriminatedUnion("format", [zod.z.object({
 	format: zod.z.literal("openvino"),
@@ -4330,7 +4345,8 @@ var ModelConvertMetadataSchema = zod.z.object({
 		"ocr",
 		"segmentation"
 	]),
-	faceAlignment: zod.z.boolean().optional()
+	faceAlignment: zod.z.boolean().optional(),
+	classMap: ClassMapDefinitionSchema.optional()
 });
 var ConvertArtifactSchema = zod.z.object({
 	format: zod.z.enum(MODEL_FORMATS),
@@ -15925,6 +15941,33 @@ var NativeCropRefSchema = zod.z.object({
 		h: zod.z.number()
 	})
 });
+zod.z.object({
+	crop: zod.z.object({
+		left: zod.z.number(),
+		top: zod.z.number(),
+		width: zod.z.number().positive(),
+		height: zod.z.number().positive()
+	}).optional(),
+	content: zod.z.object({
+		width: zod.z.number().int().positive(),
+		height: zod.z.number().int().positive()
+	}),
+	fit: zod.z.enum(["stretch", "contain"]),
+	format: zod.z.enum([
+		"rgb",
+		"gray",
+		"jpeg"
+	])
+});
+var FrameRefSchema = zod.z.object({
+	registryId: zod.z.string().min(1),
+	id: zod.z.string().min(1),
+	width: zod.z.number().int().positive(),
+	height: zod.z.number().int().positive(),
+	format: zod.z.enum(["rgb", "gray"]),
+	timestamp: zod.z.number(),
+	capturedAt: zod.z.number().optional()
+});
 var ModelFormatSchema$1 = zod.z.enum([
 	"onnx",
 	"coreml",
@@ -16246,7 +16289,7 @@ var pipelineExecutorCapability = {
 		* legacy call shape used by existing benchmark code; once all
 		* callers pass it explicitly we make it required.
 		*
-		* Exactly one of `frame`, `frameHandle`, `imageBase64`,
+		* Exactly one of `frame`, `frameRef`, `frameHandle`, `imageBase64`,
 		* `referenceImage` must be provided:
 		*  - `frame`: runtime dispatch path (runner → decoded broker frame).
 		*    Carries the raw buffer, dimensions, and format; the executor
@@ -16268,6 +16311,12 @@ var pipelineExecutorCapability = {
 			steps: zod.z.array(PipelineStepInputSchema).min(1),
 			frame: FrameInputSchema.optional(),
 			/**
+			* Process-local lazy frame. Valid only when caller and provider resolve
+			* in the same execution-group process; split/cross-node callers use
+			* `frame`/`image` inline compatibility instead.
+			*/
+			frameRef: FrameRefSchema.optional(),
+			/**
 			* CB5 shm passthrough — a `FrameHandle` naming the same ring slot
 			* the decoded pixels live in. One more member of the one-of
 			* frame/frameHandle/image/imageBase64/referenceImage group.
@@ -16617,7 +16666,10 @@ var NativeCropResultSchema = zod.z.object({
 	* Which source served this crop, so a quality-sensitive consumer (the native
 	* `keyFrame`) can reject a degraded fallback:
 	* - `native` — cut from the decode worker's retained NATIVE surface (the
-	*   quality path).
+	*   quality path). A subject-tile serve is also native-resolution and stays
+	*   `native` here: the public enum cannot name `tile` without a breaking cap
+	*   change. Runner telemetry distinguishes lease vs tile via `source` on the
+	*   internal crop result (`nativeHits` vs `tileHits`).
 	* - `ram-fullframe` — the native surface MISSED but the request was full-frame,
 	*   so the ≤640 RAM `RetainedFrameStore` served it (honest lower-res; legit for
 	*   the blank-frame guard / 640-snapshot resolve, NOT for the clean keyFrame).
@@ -17108,12 +17160,41 @@ var RunnerLocalLoadSchema = zod.z.object({
 * legacy `OrchestratorMetricsSchema` shape so existing dashboards keep
 * working unchanged when they switch to reading from the runner cap.
 */
+var FrameLazyCountersSchema = zod.z.object({
+	framesDecoded: zod.z.number(),
+	framesAdmitted: zod.z.number(),
+	framesDroppedPixelFree: zod.z.number(),
+	viewsMaterialized: zod.z.number(),
+	viewsSkipped: zod.z.number(),
+	workerToRunnerBytes: zod.z.number(),
+	runnerToPoolRawBytes: zod.z.number(),
+	runnerToPoolJpegBytes: zod.z.number(),
+	onDemandFullFrameRequests: zod.z.number(),
+	onDemandCropRequests: zod.z.number(),
+	nativeHits: zod.z.number(),
+	nativeMisses: zod.z.number(),
+	tileHits: zod.z.number(),
+	tileMisses: zod.z.number(),
+	fallbackHits: zod.z.number(),
+	fallbackMisses: zod.z.number(),
+	retainedWritesAvoided: zod.z.number(),
+	residentRefs: zod.z.number(),
+	residentBytes: zod.z.number(),
+	releases: zod.z.number(),
+	evictions: zod.z.number(),
+	staleMisses: zod.z.number()
+});
+var FrameLazyMetricsSchema = zod.z.object({
+	node: FrameLazyCountersSchema,
+	cameras: zod.z.array(FrameLazyCountersSchema.extend({ deviceId: zod.z.number() }))
+});
 var RunnerLocalMetricsSchema = zod.z.object({
 	nodeId: zod.z.string(),
 	activeCameras: zod.z.number(),
 	throttledCameras: zod.z.number(),
 	avgInferenceTimeMs: zod.z.number(),
-	queueDepth: zod.z.number()
+	queueDepth: zod.z.number(),
+	frameLazy: FrameLazyMetricsSchema.optional()
 });
 /**
 * Pipeline Runner capability — runtime detection workhorse.
@@ -19197,6 +19278,9 @@ var storageProviderCapability = {
 		endDownload: method(EndDownloadInputSchema, zod.z.void(), { kind: "mutation" })
 	}
 };
+/** Profile-exported FormBuilder schema. Shape is ConfigUISchema at the UI. */
+var ProfileSettingsSchemaBridge = zod.z.unknown().nullable();
+var ProfileSettingsBagSchema = zod.z.record(zod.z.string(), zod.z.unknown());
 /**
 * A live terminal session hosted by the provider addon. Output and input do
 * NOT flow through the capability — they use the addon data plane
@@ -19231,7 +19315,9 @@ var TerminalProfileInfoSchema = zod.z.object({
 	executable: zod.z.string().optional(),
 	args: zod.z.array(zod.z.string()).readonly().optional(),
 	cwd: zod.z.string().optional(),
-	environment: zod.z.array(zod.z.string()).readonly().optional()
+	environment: zod.z.array(zod.z.string()).readonly().optional(),
+	/** ConfigUISchema for instance knobs, or null when the profile has none. */
+	settingsSchema: ProfileSettingsSchemaBridge.optional()
 });
 /**
 * A durable operator-created Terminal instance. Profiles are templates; only
@@ -19248,7 +19334,8 @@ var TerminalInstanceInfoSchema = zod.z.object({
 	executable: zod.z.string(),
 	args: zod.z.array(zod.z.string()).readonly(),
 	cwd: zod.z.string(),
-	environment: zod.z.array(zod.z.string()).readonly()
+	environment: zod.z.array(zod.z.string()).readonly(),
+	profileSettings: ProfileSettingsBagSchema
 });
 var TerminalLegacyCameraSchema = zod.z.object({
 	stableId: zod.z.string(),
@@ -19298,7 +19385,8 @@ var terminalSessionCapability = {
 			executable: zod.z.string().max(1024).optional(),
 			args: zod.z.array(zod.z.string().max(2048)).max(64).optional(),
 			cwd: zod.z.string().max(1024).optional(),
-			environment: zod.z.array(zod.z.string().max(4096)).max(64).optional()
+			environment: zod.z.array(zod.z.string().max(4096)).max(64).optional(),
+			profileSettings: ProfileSettingsBagSchema.optional()
 		}), TerminalInstanceInfoSchema, {
 			kind: "mutation",
 			auth: "admin"
@@ -19309,7 +19397,8 @@ var terminalSessionCapability = {
 			executable: zod.z.string().max(1024).optional(),
 			args: zod.z.array(zod.z.string().max(2048)).max(64).optional(),
 			cwd: zod.z.string().max(1024).optional(),
-			environment: zod.z.array(zod.z.string().max(4096)).max(64).optional()
+			environment: zod.z.array(zod.z.string().max(4096)).max(64).optional(),
+			profileSettings: ProfileSettingsBagSchema.optional()
 		}), TerminalInstanceInfoSchema, {
 			kind: "mutation",
 			auth: "admin"
@@ -23781,10 +23870,10 @@ var lawnMowerControlCapability = {
 *
 *  • The SDK (mobile / web client) consumes `getConnectionEndpoints()`
 *    to receive an ordered list of candidate base URLs it should race
-*    on connect — LAN IPv4 first (lowest latency when on same network),
-*    then public hostname (if a tunnel is up), then IPv6. The SDK can
-*    race them with short timeouts and stick with the winner for the
-*    session.
+*    on connect — LAN IPv4 and stable LAN IPv6 first (lowest latency
+*    when on the same network), then public hostname (if a tunnel is
+*    up). The SDK can race them with short timeouts and stick with the
+*    winner for the session.
 *
 * Why hub-only: agents are not directly addressable by the operator's
 * clients — they reverse-connect to the hub. Exposing their interfaces
@@ -23939,6 +24028,17 @@ var NotificationEndpointSchema = zod.z.object({
 	/** What the ranking currently resolves to (null when nothing is reachable). */
 	resolved: zod.z.string().nullable()
 });
+/**
+* The URLs the SDK / viewer should race for API access. `baseUrls` empty =
+* AUTO (every LAN IPv4 + the public tunnel). `resolved` is what that choice
+* currently expands to, so the UI can show the effective set either way.
+*/
+var ViewerEndpointsSchema = zod.z.object({
+	/** The operator's explicit race set, or empty for AUTO. */
+	baseUrls: zod.z.array(zod.z.string()).readonly(),
+	/** What the ranking currently resolves to (may be empty if nothing is up). */
+	resolved: zod.z.array(zod.z.string()).readonly()
+});
 var AllowedAddressesSchema = zod.z.object({ 
 /**
 * Allowlist of interface addresses operators have explicitly opted
@@ -23980,13 +24080,13 @@ var localNetworkCapability = {
 		*/
 		getPreferred: method(zod.z.void(), PreferredSchema),
 		/**
-		* Ordered candidate base URLs the SDK should try on connect.
-		* Includes LAN IPs (one per non-internal interface), the public
-		* tunnel hostname (when active), and loopback as a last-resort
-		* fallback. Filterable by `includeLoopback` / `ipv4Only`.
-		* Honours `getAllowedAddresses()` when set — addresses outside
-		* the allowlist are dropped (the public tunnel + loopback are
-		* always included as escape hatches).
+		* Ordered candidate base URLs (the palette the Network tab shows).
+		* Includes LAN IPv4, stable LAN IPv6, the public tunnel, and mesh when
+		* joined. Loopback is off by default. The SDK races the subset from
+		* `getViewerEndpoints`, not this full list — IPv6 stays here because
+		* WebRTC ICE gathers dual-stack regardless of the HTTP race. Honours
+		* `getAllowedAddresses()` when set — addresses outside the allowlist
+		* are dropped (the public tunnel is still included as an escape hatch).
 		*
 		* **The port is the hub's, not the caller's** (D62 — a function's fact
 		* belongs to whoever already owns it). This method used to take a `port`
@@ -24017,10 +24117,11 @@ var localNetworkCapability = {
 			*/
 			port: zod.z.number().int().min(1).max(65535).optional(),
 			/** Include `http(s)://127.0.0.1:<port>` as the lowest-priority
-			*  candidate. Default `true`. */
+			*  candidate. Default `false` — loopback is not a client route. */
 			includeLoopback: zod.z.boolean().optional(),
-			/** Skip IPv6 entries. Some legacy clients can't parse them.
-			*  Default `false`. */
+			/** Skip IPv6 entries. Default `false` — the palette includes stable
+			*  LAN IPv6 (ICE/WebRTC uses dual-stack regardless). Pass `true` to
+			*  hide them. The viewer HTTP/WS race is `getViewerEndpoints`. */
 			ipv4Only: zod.z.boolean().optional(),
 			/** Scheme to emit for LAN/loopback URLs. Default `'http'`.
 			*  Pass `'https'` when the caller is itself loaded over HTTPS
@@ -24049,6 +24150,19 @@ var localNetworkCapability = {
 		*/
 		setNotificationEndpoint: method(zod.z.object({ baseUrl: zod.z.string().nullable() }), NotificationEndpointSchema, { kind: "mutation" }),
 		/**
+		* The endpoints the SDK / viewer races for API access. Empty `baseUrls`
+		* means AUTO: every LAN IPv4 address plus the public tunnel, never IPv6,
+		* never mesh, never loopback. `resolved` is that set (or the operator's
+		* explicit subset) as it stands right now.
+		*/
+		getViewerEndpoints: method(zod.z.void(), ViewerEndpointsSchema),
+		/**
+		* Replace the viewer race set. Empty `baseUrls` restores AUTO. Stored
+		* verbatim (not indices) so a temporarily-down tunnel is not silently
+		* dropped from the operator's choice.
+		*/
+		setViewerEndpoints: method(zod.z.object({ baseUrls: zod.z.array(zod.z.string()).readonly() }), ViewerEndpointsSchema, { kind: "mutation" }),
+		/**
 		* Read the operator's allowlist. Empty = "auto" (no filter). Used
 		* by the admin UI's address selector to seed its checkbox state.
 		*/
@@ -32583,6 +32697,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"localNetwork.getViewerEndpoints": {
+		capName: "local-network",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"localNetwork.list": {
 		capName: "local-network",
 		capScope: "system",
@@ -32619,6 +32739,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"localNetwork.setViewerEndpoints": {
+		capName: "local-network",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"localNetwork.uploadCertificate": {
 		capName: "local-network",
 		capScope: "system",

package/dist/{dist-BpzbLPel.mjs → dist-DCTpBXm4.mjs}

@@ -4123,6 +4123,15 @@ var LabelDefinitionSchema = z.object({
 	description: z.string().optional(),
 	icon: z.string().optional()
 });
+var ClassMapDefinitionSchema = z.object({
+	mapping: z.record(z.string(), z.enum([
+		"person",
+		"vehicle",
+		"animal",
+		"package"
+	])),
+	preserveOriginal: z.boolean()
+});
 var MODEL_FORMATS = [
 	"onnx",
 	"coreml",
@@ -4301,7 +4310,13 @@ var ModelCatalogEntrySchema = z.object({
 	* `id` stays the source of truth for resolution/download/persistence; grouping
 	* is a presentation overlay resolved back to an `id`.
 	*/
-	group: ModelVariantGroupSchema.optional()
+	group: ModelVariantGroupSchema.optional(),
+	/**
+	* Per-MODEL class map override. Absent ⇒ the step's `StepDefinition.classMap`
+	* applies (Frigate / COCO public catalog). Set on a custom model whose raw
+	* labels already ARE the CamStack macros (Scrypted identity map).
+	*/
+	classMap: ClassMapDefinitionSchema.optional()
 });
 var ConvertTargetSchema = z.discriminatedUnion("format", [z.object({
 	format: z.literal("openvino"),
@@ -4330,7 +4345,8 @@ var ModelConvertMetadataSchema = z.object({
 		"ocr",
 		"segmentation"
 	]),
-	faceAlignment: z.boolean().optional()
+	faceAlignment: z.boolean().optional(),
+	classMap: ClassMapDefinitionSchema.optional()
 });
 var ConvertArtifactSchema = z.object({
 	format: z.enum(MODEL_FORMATS),
@@ -15925,6 +15941,33 @@ var NativeCropRefSchema = z.object({
 		h: z.number()
 	})
 });
+z.object({
+	crop: z.object({
+		left: z.number(),
+		top: z.number(),
+		width: z.number().positive(),
+		height: z.number().positive()
+	}).optional(),
+	content: z.object({
+		width: z.number().int().positive(),
+		height: z.number().int().positive()
+	}),
+	fit: z.enum(["stretch", "contain"]),
+	format: z.enum([
+		"rgb",
+		"gray",
+		"jpeg"
+	])
+});
+var FrameRefSchema = z.object({
+	registryId: z.string().min(1),
+	id: z.string().min(1),
+	width: z.number().int().positive(),
+	height: z.number().int().positive(),
+	format: z.enum(["rgb", "gray"]),
+	timestamp: z.number(),
+	capturedAt: z.number().optional()
+});
 var ModelFormatSchema$1 = z.enum([
 	"onnx",
 	"coreml",
@@ -16246,7 +16289,7 @@ var pipelineExecutorCapability = {
 		* legacy call shape used by existing benchmark code; once all
 		* callers pass it explicitly we make it required.
 		*
-		* Exactly one of `frame`, `frameHandle`, `imageBase64`,
+		* Exactly one of `frame`, `frameRef`, `frameHandle`, `imageBase64`,
 		* `referenceImage` must be provided:
 		*  - `frame`: runtime dispatch path (runner → decoded broker frame).
 		*    Carries the raw buffer, dimensions, and format; the executor
@@ -16268,6 +16311,12 @@ var pipelineExecutorCapability = {
 			steps: z.array(PipelineStepInputSchema).min(1),
 			frame: FrameInputSchema.optional(),
 			/**
+			* Process-local lazy frame. Valid only when caller and provider resolve
+			* in the same execution-group process; split/cross-node callers use
+			* `frame`/`image` inline compatibility instead.
+			*/
+			frameRef: FrameRefSchema.optional(),
+			/**
 			* CB5 shm passthrough — a `FrameHandle` naming the same ring slot
 			* the decoded pixels live in. One more member of the one-of
 			* frame/frameHandle/image/imageBase64/referenceImage group.
@@ -16617,7 +16666,10 @@ var NativeCropResultSchema = z.object({
 	* Which source served this crop, so a quality-sensitive consumer (the native
 	* `keyFrame`) can reject a degraded fallback:
 	* - `native` — cut from the decode worker's retained NATIVE surface (the
-	*   quality path).
+	*   quality path). A subject-tile serve is also native-resolution and stays
+	*   `native` here: the public enum cannot name `tile` without a breaking cap
+	*   change. Runner telemetry distinguishes lease vs tile via `source` on the
+	*   internal crop result (`nativeHits` vs `tileHits`).
 	* - `ram-fullframe` — the native surface MISSED but the request was full-frame,
 	*   so the ≤640 RAM `RetainedFrameStore` served it (honest lower-res; legit for
 	*   the blank-frame guard / 640-snapshot resolve, NOT for the clean keyFrame).
@@ -17108,12 +17160,41 @@ var RunnerLocalLoadSchema = z.object({
 * legacy `OrchestratorMetricsSchema` shape so existing dashboards keep
 * working unchanged when they switch to reading from the runner cap.
 */
+var FrameLazyCountersSchema = z.object({
+	framesDecoded: z.number(),
+	framesAdmitted: z.number(),
+	framesDroppedPixelFree: z.number(),
+	viewsMaterialized: z.number(),
+	viewsSkipped: z.number(),
+	workerToRunnerBytes: z.number(),
+	runnerToPoolRawBytes: z.number(),
+	runnerToPoolJpegBytes: z.number(),
+	onDemandFullFrameRequests: z.number(),
+	onDemandCropRequests: z.number(),
+	nativeHits: z.number(),
+	nativeMisses: z.number(),
+	tileHits: z.number(),
+	tileMisses: z.number(),
+	fallbackHits: z.number(),
+	fallbackMisses: z.number(),
+	retainedWritesAvoided: z.number(),
+	residentRefs: z.number(),
+	residentBytes: z.number(),
+	releases: z.number(),
+	evictions: z.number(),
+	staleMisses: z.number()
+});
+var FrameLazyMetricsSchema = z.object({
+	node: FrameLazyCountersSchema,
+	cameras: z.array(FrameLazyCountersSchema.extend({ deviceId: z.number() }))
+});
 var RunnerLocalMetricsSchema = z.object({
 	nodeId: z.string(),
 	activeCameras: z.number(),
 	throttledCameras: z.number(),
 	avgInferenceTimeMs: z.number(),
-	queueDepth: z.number()
+	queueDepth: z.number(),
+	frameLazy: FrameLazyMetricsSchema.optional()
 });
 /**
 * Pipeline Runner capability — runtime detection workhorse.
@@ -19197,6 +19278,9 @@ var storageProviderCapability = {
 		endDownload: method(EndDownloadInputSchema, z.void(), { kind: "mutation" })
 	}
 };
+/** Profile-exported FormBuilder schema. Shape is ConfigUISchema at the UI. */
+var ProfileSettingsSchemaBridge = z.unknown().nullable();
+var ProfileSettingsBagSchema = z.record(z.string(), z.unknown());
 /**
 * A live terminal session hosted by the provider addon. Output and input do
 * NOT flow through the capability — they use the addon data plane
@@ -19231,7 +19315,9 @@ var TerminalProfileInfoSchema = z.object({
 	executable: z.string().optional(),
 	args: z.array(z.string()).readonly().optional(),
 	cwd: z.string().optional(),
-	environment: z.array(z.string()).readonly().optional()
+	environment: z.array(z.string()).readonly().optional(),
+	/** ConfigUISchema for instance knobs, or null when the profile has none. */
+	settingsSchema: ProfileSettingsSchemaBridge.optional()
 });
 /**
 * A durable operator-created Terminal instance. Profiles are templates; only
@@ -19248,7 +19334,8 @@ var TerminalInstanceInfoSchema = z.object({
 	executable: z.string(),
 	args: z.array(z.string()).readonly(),
 	cwd: z.string(),
-	environment: z.array(z.string()).readonly()
+	environment: z.array(z.string()).readonly(),
+	profileSettings: ProfileSettingsBagSchema
 });
 var TerminalLegacyCameraSchema = z.object({
 	stableId: z.string(),
@@ -19298,7 +19385,8 @@ var terminalSessionCapability = {
 			executable: z.string().max(1024).optional(),
 			args: z.array(z.string().max(2048)).max(64).optional(),
 			cwd: z.string().max(1024).optional(),
-			environment: z.array(z.string().max(4096)).max(64).optional()
+			environment: z.array(z.string().max(4096)).max(64).optional(),
+			profileSettings: ProfileSettingsBagSchema.optional()
 		}), TerminalInstanceInfoSchema, {
 			kind: "mutation",
 			auth: "admin"
@@ -19309,7 +19397,8 @@ var terminalSessionCapability = {
 			executable: z.string().max(1024).optional(),
 			args: z.array(z.string().max(2048)).max(64).optional(),
 			cwd: z.string().max(1024).optional(),
-			environment: z.array(z.string().max(4096)).max(64).optional()
+			environment: z.array(z.string().max(4096)).max(64).optional(),
+			profileSettings: ProfileSettingsBagSchema.optional()
 		}), TerminalInstanceInfoSchema, {
 			kind: "mutation",
 			auth: "admin"
@@ -23781,10 +23870,10 @@ var lawnMowerControlCapability = {
 *
 *  • The SDK (mobile / web client) consumes `getConnectionEndpoints()`
 *    to receive an ordered list of candidate base URLs it should race
-*    on connect — LAN IPv4 first (lowest latency when on same network),
-*    then public hostname (if a tunnel is up), then IPv6. The SDK can
-*    race them with short timeouts and stick with the winner for the
-*    session.
+*    on connect — LAN IPv4 and stable LAN IPv6 first (lowest latency
+*    when on the same network), then public hostname (if a tunnel is
+*    up). The SDK can race them with short timeouts and stick with the
+*    winner for the session.
 *
 * Why hub-only: agents are not directly addressable by the operator's
 * clients — they reverse-connect to the hub. Exposing their interfaces
@@ -23939,6 +24028,17 @@ var NotificationEndpointSchema = z.object({
 	/** What the ranking currently resolves to (null when nothing is reachable). */
 	resolved: z.string().nullable()
 });
+/**
+* The URLs the SDK / viewer should race for API access. `baseUrls` empty =
+* AUTO (every LAN IPv4 + the public tunnel). `resolved` is what that choice
+* currently expands to, so the UI can show the effective set either way.
+*/
+var ViewerEndpointsSchema = z.object({
+	/** The operator's explicit race set, or empty for AUTO. */
+	baseUrls: z.array(z.string()).readonly(),
+	/** What the ranking currently resolves to (may be empty if nothing is up). */
+	resolved: z.array(z.string()).readonly()
+});
 var AllowedAddressesSchema = z.object({ 
 /**
 * Allowlist of interface addresses operators have explicitly opted
@@ -23980,13 +24080,13 @@ var localNetworkCapability = {
 		*/
 		getPreferred: method(z.void(), PreferredSchema),
 		/**
-		* Ordered candidate base URLs the SDK should try on connect.
-		* Includes LAN IPs (one per non-internal interface), the public
-		* tunnel hostname (when active), and loopback as a last-resort
-		* fallback. Filterable by `includeLoopback` / `ipv4Only`.
-		* Honours `getAllowedAddresses()` when set — addresses outside
-		* the allowlist are dropped (the public tunnel + loopback are
-		* always included as escape hatches).
+		* Ordered candidate base URLs (the palette the Network tab shows).
+		* Includes LAN IPv4, stable LAN IPv6, the public tunnel, and mesh when
+		* joined. Loopback is off by default. The SDK races the subset from
+		* `getViewerEndpoints`, not this full list — IPv6 stays here because
+		* WebRTC ICE gathers dual-stack regardless of the HTTP race. Honours
+		* `getAllowedAddresses()` when set — addresses outside the allowlist
+		* are dropped (the public tunnel is still included as an escape hatch).
 		*
 		* **The port is the hub's, not the caller's** (D62 — a function's fact
 		* belongs to whoever already owns it). This method used to take a `port`
@@ -24017,10 +24117,11 @@ var localNetworkCapability = {
 			*/
 			port: z.number().int().min(1).max(65535).optional(),
 			/** Include `http(s)://127.0.0.1:<port>` as the lowest-priority
-			*  candidate. Default `true`. */
+			*  candidate. Default `false` — loopback is not a client route. */
 			includeLoopback: z.boolean().optional(),
-			/** Skip IPv6 entries. Some legacy clients can't parse them.
-			*  Default `false`. */
+			/** Skip IPv6 entries. Default `false` — the palette includes stable
+			*  LAN IPv6 (ICE/WebRTC uses dual-stack regardless). Pass `true` to
+			*  hide them. The viewer HTTP/WS race is `getViewerEndpoints`. */
 			ipv4Only: z.boolean().optional(),
 			/** Scheme to emit for LAN/loopback URLs. Default `'http'`.
 			*  Pass `'https'` when the caller is itself loaded over HTTPS
@@ -24049,6 +24150,19 @@ var localNetworkCapability = {
 		*/
 		setNotificationEndpoint: method(z.object({ baseUrl: z.string().nullable() }), NotificationEndpointSchema, { kind: "mutation" }),
 		/**
+		* The endpoints the SDK / viewer races for API access. Empty `baseUrls`
+		* means AUTO: every LAN IPv4 address plus the public tunnel, never IPv6,
+		* never mesh, never loopback. `resolved` is that set (or the operator's
+		* explicit subset) as it stands right now.
+		*/
+		getViewerEndpoints: method(z.void(), ViewerEndpointsSchema),
+		/**
+		* Replace the viewer race set. Empty `baseUrls` restores AUTO. Stored
+		* verbatim (not indices) so a temporarily-down tunnel is not silently
+		* dropped from the operator's choice.
+		*/
+		setViewerEndpoints: method(z.object({ baseUrls: z.array(z.string()).readonly() }), ViewerEndpointsSchema, { kind: "mutation" }),
+		/**
 		* Read the operator's allowlist. Empty = "auto" (no filter). Used
 		* by the admin UI's address selector to seed its checkbox state.
 		*/
@@ -32583,6 +32697,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "view"
 	},
+	"localNetwork.getViewerEndpoints": {
+		capName: "local-network",
+		capScope: "system",
+		addonId: null,
+		access: "view"
+	},
 	"localNetwork.list": {
 		capName: "local-network",
 		capScope: "system",
@@ -32619,6 +32739,12 @@ var METHOD_ACCESS_MAP = Object.freeze({
 		addonId: null,
 		access: "create"
 	},
+	"localNetwork.setViewerEndpoints": {
+		capName: "local-network",
+		capScope: "system",
+		addonId: null,
+		access: "create"
+	},
 	"localNetwork.uploadCertificate": {
 		capName: "local-network",
 		capScope: "system",

package/dist/download/model-downloader.d.ts

@@ -23,13 +23,30 @@ export declare function siblingUrl(mainUrl: string, sibling: string): string;
  * agree on the on-disk layout without re-deriving it.
  */
 export declare function collectModelFiles(entry: ModelCatalogEntry, format: ModelFormat): string[];
+export type DownloadRedirectPolicy = (url: URL, hop: number) => void;
+export interface DownloadFileOptions {
+    readonly onProgress?: (downloaded: number, total: number) => void;
+    /**
+     * When set, redirects are followed manually and THIS policy is applied to
+     * the initial URL and every Location hop before the next fetch. Absent ⇒
+     * native `redirect: 'follow'` (backward compatible).
+     */
+    readonly redirectPolicy?: DownloadRedirectPolicy;
+    readonly maxRedirects?: number;
+    readonly timeoutMs?: number;
+    readonly maxBytes?: number;
+    readonly fetchImpl?: typeof fetch;
+}
 /**
  * Download a single file from a URL to a destination path.
- * Uses native fetch() (Node 22+) which handles redirects natively.
  * Streams to disk with optional progress callback.
  * Returns the destination path. Skips download if file already exists.
+ *
+ * The third argument remains a progress callback for existing callers. Pass
+ * an options object to supply a per-hop redirect policy, timeout, or byte cap.
  */
 export declare function downloadFile(url: string, destPath: string, onProgress?: (downloaded: number, total: number) => void): Promise<string>;
+export declare function downloadFile(url: string, destPath: string, options: DownloadFileOptions): Promise<string>;
 /**
  * Fetch JSON from a URL using native fetch().
  */