dsh-input-traffic 0.7.0 → 0.7.3

package/lib/index.js

@@ -1,5 +1,197 @@
+//#region lib/types/bridge.js
+/** Route pair for one settings ns — client and server must derive identically. */
+function bridgeRoutesFor(ns) {
+	return {
+		describe: `/api/${ns}/settings/describe`,
+		mutate: `/api/${ns}/settings/mutate`
+	};
+}
+function readJsonBody(reqRaw, limit = 262144) {
+	const req = reqRaw;
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		let size = 0;
+		req.on("data", (chunk) => {
+			const buf = chunk;
+			size += buf.length;
+			if (size > limit) {
+				reject(/* @__PURE__ */ new Error("bridge body too large"));
+				req.resume?.();
+				return;
+			}
+			chunks.push(buf);
+		});
+		req.on("end", () => {
+			const raw = Buffer.concat(chunks).toString("utf8");
+			if (raw === "") {
+				resolve({});
+				return;
+			}
+			try {
+				resolve(JSON.parse(raw));
+			} catch (e) {
+				reject(e instanceof Error ? e : new Error(String(e)));
+			}
+		});
+		req.on("error", reject);
+	});
+}
+function sendJson(res, code, body) {
+	res.writeHead(code, {
+		"content-type": "application/json; charset=utf-8",
+		"cache-control": "no-cache"
+	});
+	res.end(JSON.stringify(body));
+}
+function isConflict(e) {
+	return e instanceof Error && /conflict|revision/i.test(e.message);
+}
+function registerSettingsBridgeRoutes(server, getSettingsSvc, ns) {
+	if (typeof server !== "object" || server === null) return [];
+	const ws = typeof server.register === "function" ? server : void 0;
+	if (ws === void 0) return [];
+	const offs = [];
+	const routes = bridgeRoutesFor(ns);
+	offs.push(ws.register({
+		kind: "exact",
+		path: routes.describe,
+		handler: (rawReq, rawRes) => {
+			const req = rawReq;
+			const res = rawRes;
+			if (req.method !== "POST") {
+				sendJson(res, 405, {
+					ok: false,
+					code: "method-not-allowed"
+				});
+				return;
+			}
+			const svc = getSettingsSvc();
+			if (svc === void 0 || typeof svc.describe !== "function") {
+				sendJson(res, 200, {
+					ok: false,
+					code: "settings-unavailable",
+					message: "settings service not resolved yet"
+				});
+				return;
+			}
+			try {
+				const descriptor = svc.describe({ redactSecrets: true }).find((d) => d.ns === ns);
+				if (descriptor === void 0) {
+					sendJson(res, 200, {
+						ok: false,
+						code: "ns-not-registered",
+						message: `settings namespace "${ns}" is not registered`
+					});
+					return;
+				}
+				sendJson(res, 200, {
+					ok: true,
+					value: {
+						descriptor,
+						writable: svc.writable !== false
+					}
+				});
+			} catch (e) {
+				sendJson(res, 200, {
+					ok: false,
+					code: "internal",
+					message: e instanceof Error ? e.message : String(e)
+				});
+			}
+		}
+	}));
+	offs.push(ws.register({
+		kind: "exact",
+		path: routes.mutate,
+		handler: (rawReq, rawRes) => {
+			const req = rawReq;
+			const res = rawRes;
+			if (req.method !== "POST") {
+				sendJson(res, 405, {
+					ok: false,
+					code: "method-not-allowed"
+				});
+				return;
+			}
+			const svc = getSettingsSvc();
+			const mutate = svc === void 0 ? void 0 : svc.mutate;
+			if (typeof mutate !== "function") {
+				sendJson(res, 200, {
+					ok: false,
+					code: "settings-unavailable",
+					message: "settings service mutate not available"
+				});
+				return;
+			}
+			readJsonBody(req).then((body) => {
+				const ops = body.ops;
+				if (!Array.isArray(ops) || ops.some((op) => !op || typeof op !== "object" || !(op.op in {
+					set: 1,
+					unset: 1
+				}))) {
+					sendJson(res, 200, {
+						ok: false,
+						code: "settings-rejected",
+						message: "malformed bridge mutate ops"
+					});
+					return;
+				}
+				const expectedRevision = typeof body.expectedRevision === "number" ? body.expectedRevision : void 0;
+				mutate.call(svc, ns, ops, expectedRevision).then(() => {
+					const descriptor = svc.describe({ redactSecrets: true }).find((d) => d.ns === ns);
+					if (descriptor === void 0) {
+						sendJson(res, 200, {
+							ok: false,
+							code: "internal",
+							message: `namespace "${ns}" disposed after mutate`
+						});
+						return;
+					}
+					sendJson(res, 200, {
+						ok: true,
+						value: { descriptor }
+					});
+				}).catch((e) => {
+					sendJson(res, 200, isConflict(e) ? {
+						ok: false,
+						code: "settings-conflict",
+						message: e instanceof Error ? e.message : String(e)
+					} : {
+						ok: false,
+						code: "internal",
+						message: e instanceof Error ? e.message : String(e)
+					});
+				});
+			}).catch((e) => {
+				sendJson(res, 200, {
+					ok: false,
+					code: "bad-request",
+					message: e instanceof Error ? e.message : String(e)
+				});
+			});
+		}
+	}));
+	return offs;
+}
+//#endregion
 //#region lib/types/index.js
-/** @param ctx - host-side context; intentionally unused (client-plugin shape). */
-function apply(ctx) {}
+/** The settings namespace the browser half pins (`ui-conversation.busyEnter`). */
+const BRIDGE_NS = "ui-conversation";
+/** webServer hosts the bridge route pair. */
+const inject = ["webServer"];
+/** @param ctx - host-side context; registers the bridge route pair. */
+function apply(ctx) {
+	const settingsRef = {};
+	ctx.inject(["settings"], (child) => {
+		settingsRef.svc = child.settings;
+	});
+	ctx.effect(() => {
+		const injected = ctx;
+		const offs = registerSettingsBridgeRoutes(injected.webServer ?? injected.get?.("webServer"), () => settingsRef.svc, BRIDGE_NS);
+		return () => {
+			for (const off of offs) off();
+		};
+	}, "dsh-input-traffic: settings bridge routes");
+}
 //#endregion
-export { apply };
+export { apply, inject };

package/lib/types/bridge.d.ts

@@ -0,0 +1,45 @@
+/**
+ * settings bridge — T20-b port from dsh-perm-gate (5260fe6 generalized form).
+ *
+ * The plugin is a pure client takeover on every host line, but its durable
+ * data plane (the `ui-conversation` busy-Enter pin) rides the client settings
+ * handles that are generation-exclusive: `configForms` (0.1.7+) works,
+ * `settingsScope` (≤0.1.5) resolves to nothing (the A2 dead end), so on old
+ * lines both the family card and the pin itself silently no-op. This bridge
+ * gives the browser half a same-origin HTTP data plane backed by the HOST's
+ * settings service — reads = svc.describe of our ns, writes = svc.mutate ops.
+ * No second copy of state: the service stays the single source of truth.
+ * Guards: POST-only, ns fixed at registration, optimistic concurrency via
+ * expectedRevision. The 0.1.0 host settings service carries the full
+ * describe/mutate/redactSecrets surface (lib/index.js verified), so the
+ * oldest line needs no fallback path.
+ *
+ * Data consumer = client BridgeDocHandle (src/client/bridge-scope.ts) — the
+ * T13b dual-track: native handle first (0.1.7+), this bridge underneath.
+ * Routes derive from the ns (bridgeRoutesFor) so the URL contract cannot
+ * drift between the two halves; the parity test pins both derivations
+ * character-for-character.
+ */
+interface SettingsServiceLike {
+    update?(ns: string, patch: object): Promise<void>;
+    describe?(o?: {
+        redactSecrets?: boolean;
+    }): Array<{
+        ns: unknown;
+        [k: string]: unknown;
+    }>;
+    mutate?(ns: string, ops: Array<{
+        op: string;
+        path: string[];
+        value?: unknown;
+    }>, expectedRevision?: number): Promise<unknown>;
+    writable?: boolean;
+}
+/** Route pair for one settings ns — client and server must derive identically. */
+export declare function bridgeRoutesFor(ns: string): {
+    describe: string;
+    mutate: string;
+};
+export declare function registerSettingsBridgeRoutes(server: unknown, getSettingsSvc: () => SettingsServiceLike | undefined, ns: string): Array<() => void>;
+export {};
+//# sourceMappingURL=bridge.d.ts.map

package/lib/types/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../../src/bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,UAAU,mBAAmB;IAC3B,MAAM,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACjD,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,KAAK,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC,CAAA;IACxF,MAAM,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC,EAAE,gBAAgB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAC7H,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAED,kFAAkF;AAClF,wBAAgB,eAAe,CAAC,EAAE,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAEhF;AAuCD,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,OAAO,EACf,cAAc,EAAE,MAAM,mBAAmB,GAAG,SAAS,EACrD,EAAE,EAAE,MAAM,GACT,KAAK,CAAC,MAAM,IAAI,CAAC,CA6EnB"}

package/lib/types/bridge.js

@@ -0,0 +1,130 @@
+/** Route pair for one settings ns — client and server must derive identically. */
+export function bridgeRoutesFor(ns) {
+    return { describe: `/api/${ns}/settings/describe`, mutate: `/api/${ns}/settings/mutate` };
+}
+function readJsonBody(reqRaw, limit = 256 * 1024) {
+    const req = reqRaw;
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on('data', (chunk) => {
+            const buf = chunk;
+            size += buf.length;
+            if (size > limit) {
+                reject(new Error('bridge body too large'));
+                req.resume?.();
+                return;
+            }
+            chunks.push(buf);
+        });
+        req.on('end', () => {
+            const raw = Buffer.concat(chunks).toString('utf8');
+            if (raw === '') {
+                resolve({});
+                return;
+            }
+            try {
+                resolve(JSON.parse(raw));
+            }
+            catch (e) {
+                reject(e instanceof Error ? e : new Error(String(e)));
+            }
+        });
+        req.on('error', reject);
+    });
+}
+function sendJson(res, code, body) {
+    res.writeHead(code, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-cache' });
+    res.end(JSON.stringify(body));
+}
+function isConflict(e) {
+    return e instanceof Error && /conflict|revision/i.test(e.message);
+}
+export function registerSettingsBridgeRoutes(server, getSettingsSvc, ns) {
+    if (typeof server !== 'object' || server === null)
+        return [];
+    const ws = typeof server.register === 'function' ? server : undefined;
+    if (ws === undefined)
+        return [];
+    const offs = [];
+    const routes = bridgeRoutesFor(ns);
+    offs.push(ws.register({
+        kind: 'exact',
+        path: routes.describe,
+        handler: (rawReq, rawRes) => {
+            const req = rawReq;
+            const res = rawRes;
+            if (req.method !== 'POST') {
+                sendJson(res, 405, { ok: false, code: 'method-not-allowed' });
+                return;
+            }
+            const svc = getSettingsSvc();
+            if (svc === undefined || typeof svc.describe !== 'function') {
+                sendJson(res, 200, { ok: false, code: 'settings-unavailable', message: 'settings service not resolved yet' });
+                return;
+            }
+            try {
+                const descriptor = svc
+                    .describe({ redactSecrets: true })
+                    .find((d) => d.ns === ns);
+                if (descriptor === undefined) {
+                    sendJson(res, 200, { ok: false, code: 'ns-not-registered', message: `settings namespace "${ns}" is not registered` });
+                    return;
+                }
+                sendJson(res, 200, { ok: true, value: { descriptor, writable: svc.writable !== false } });
+            }
+            catch (e) {
+                sendJson(res, 200, { ok: false, code: 'internal', message: e instanceof Error ? e.message : String(e) });
+            }
+        },
+    }));
+    offs.push(ws.register({
+        kind: 'exact',
+        path: routes.mutate,
+        handler: (rawReq, rawRes) => {
+            const req = rawReq;
+            const res = rawRes;
+            if (req.method !== 'POST') {
+                sendJson(res, 405, { ok: false, code: 'method-not-allowed' });
+                return;
+            }
+            const svc = getSettingsSvc();
+            const mutate = svc === undefined ? undefined : svc.mutate;
+            if (typeof mutate !== 'function') {
+                sendJson(res, 200, { ok: false, code: 'settings-unavailable', message: 'settings service mutate not available' });
+                return;
+            }
+            readJsonBody(req).then((body) => {
+                const ops = body.ops;
+                if (!Array.isArray(ops) || ops.some((op) => !op || typeof op !== 'object' || !(op.op in { set: 1, unset: 1 }))) {
+                    sendJson(res, 200, { ok: false, code: 'settings-rejected', message: 'malformed bridge mutate ops' });
+                    return;
+                }
+                const expectedRevision = typeof body.expectedRevision === 'number' ? body.expectedRevision : undefined;
+                mutate
+                    .call(svc, ns, ops, expectedRevision)
+                    .then(() => {
+                    // Successful mutate re-describes: writes stay funneled through the
+                    // host service, no shadow state anywhere.
+                    const descriptor = svc
+                        .describe({ redactSecrets: true })
+                        .find((d) => d.ns === ns);
+                    if (descriptor === undefined) {
+                        sendJson(res, 200, { ok: false, code: 'internal', message: `namespace "${ns}" disposed after mutate` });
+                        return;
+                    }
+                    sendJson(res, 200, { ok: true, value: { descriptor } });
+                })
+                    .catch((e) => {
+                    sendJson(res, 200, isConflict(e)
+                        ? { ok: false, code: 'settings-conflict', message: e instanceof Error ? e.message : String(e) }
+                        : { ok: false, code: 'internal', message: e instanceof Error ? e.message : String(e) });
+                });
+            }).catch((e) => {
+                sendJson(res, 200, { ok: false, code: 'bad-request', message: e instanceof Error ? e.message : String(e) });
+            });
+        },
+    }));
+    return offs;
+}
+//# sourceMappingURL=bridge.js.map

package/lib/types/bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.js","sourceRoot":"","sources":["../../src/bridge.ts"],"names":[],"mappings":"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"}

package/lib/types/client/bridge-scope.d.ts

@@ -0,0 +1,38 @@
+/**
+ * BridgeDocHandle — T20-b port from dsh-perm-gate (bridge-scope.ts, the
+ * client half of the settings bridge).
+ *
+ * Shape-compatible with the native durable-settings handle (configForms.get /
+ * settingsScope.bind subset): getSnapshot/subscribe/set. Reads POST
+ * /api/<ns>/settings/describe, writes POST …/mutate (ops forwarded to the
+ * host settings service); a successful write re-describes and refreshes the
+ * snapshot (optimistic refresh, no local second copy of state — the service
+ * stays authoritative). The initial describe fetch starts at construction;
+ * the snapshot is `pending` until it lands, and the family card renders its
+ * pinned default meanwhile.
+ *
+ * The route derivation must stay character-identical to the server side
+ * (src/bridge.ts bridgeRoutesFor); the client tsconfig only includes
+ * src/client, so this half holds its own copy and the parity test pins both.
+ */
+import type { SettingsDocHandle } from './compat.js';
+/** The native handle's snapshot shape — the bridge payload cast at the boundary. */
+type DocSnapshot = ReturnType<SettingsDocHandle['getSnapshot']>;
+export declare class BridgeDocHandle implements SettingsDocHandle {
+    private snapshot;
+    private listeners;
+    private revision;
+    private inflight;
+    private readonly routes;
+    constructor(ns: string);
+    /** The bridge transport is shape-agnostic; the ns payload narrows at this boundary. */
+    getSnapshot(): DocSnapshot;
+    subscribe(listener: () => void): () => void;
+    set(field: string, value: unknown): Promise<void>;
+    private notify;
+    private request;
+    private refresh;
+    private mutate;
+}
+export {};
+//# sourceMappingURL=bridge-scope.d.ts.map

package/lib/types/client/bridge-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-scope.d.ts","sourceRoot":"","sources":["../../../src/client/bridge-scope.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAOpD,oFAAoF;AACpF,KAAK,WAAW,GAAG,UAAU,CAAC,iBAAiB,CAAC,aAAa,CAAC,CAAC,CAAA;AAM/D,qBAAa,eAAgB,YAAW,iBAAiB;IACvD,OAAO,CAAC,QAAQ,CAAoE;IACpF,OAAO,CAAC,SAAS,CAAwB;IACzC,OAAO,CAAC,QAAQ,CAAoB;IACpC,OAAO,CAAC,QAAQ,CAA2B;IAC3C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsC;gBAEjD,EAAE,EAAE,MAAM;IAKtB,uFAAuF;IACvF,WAAW,IAAI,WAAW;IAI1B,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAKrC,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAIvD,OAAO,CAAC,MAAM;YAIA,OAAO;YAUP,OAAO;YAsBP,MAAM;CAarB"}

package/lib/types/client/bridge-scope.js

@@ -0,0 +1,81 @@
+/** Must match src/bridge.ts bridgeRoutesFor character for character. */
+function bridgeRoutesFor(ns) {
+    return { describe: `/api/${ns}/settings/describe`, mutate: `/api/${ns}/settings/mutate` };
+}
+export class BridgeDocHandle {
+    snapshot = { status: 'pending', value: undefined, writable: true };
+    listeners = new Set();
+    revision;
+    inflight;
+    routes;
+    constructor(ns) {
+        this.routes = bridgeRoutesFor(ns);
+        void this.refresh();
+    }
+    /** The bridge transport is shape-agnostic; the ns payload narrows at this boundary. */
+    getSnapshot() {
+        return this.snapshot;
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+    async set(field, value) {
+        await this.mutate([{ op: 'set', path: [field], value }]);
+    }
+    notify() {
+        for (const l of [...this.listeners])
+            l();
+    }
+    async request(path, body) {
+        const response = await fetch(path, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(body ?? {}),
+        });
+        if (!response.ok)
+            throw new Error(`bridge ${path} HTTP ${response.status}`);
+        return await response.json();
+    }
+    async refresh() {
+        if (this.inflight !== undefined)
+            return this.inflight;
+        this.inflight = (async () => {
+            try {
+                const body = await this.request(this.routes.describe);
+                if (body.ok && body.value?.descriptor !== undefined) {
+                    const d = body.value.descriptor;
+                    this.revision = typeof d.revision === 'number' ? d.revision : undefined;
+                    this.snapshot = { status: 'ready', value: d.value, writable: body.value.writable !== false };
+                }
+                else {
+                    this.snapshot = { status: 'error', value: undefined, writable: false };
+                }
+            }
+            catch {
+                this.snapshot = { status: 'error', value: undefined, writable: false };
+            }
+            finally {
+                this.inflight = undefined;
+            }
+            this.notify();
+        })();
+        return this.inflight;
+    }
+    async mutate(ops) {
+        const body = await this.request(this.routes.mutate, { ops, expectedRevision: this.revision });
+        if (body.ok && body.value?.descriptor !== undefined) {
+            const d = body.value.descriptor;
+            this.revision = typeof d.revision === 'number' ? d.revision : undefined;
+            this.snapshot = { status: 'ready', value: d.value, writable: this.snapshot.writable };
+        }
+        else if (body.code === 'settings-conflict') {
+            await this.refresh(); // optimistic concurrency lost: pull the authoritative value so the next write carries a fresh revision
+        }
+        else {
+            throw new Error(`bridge mutate failed: ${body.code ?? 'unknown'} ${body.message ?? ''}`);
+        }
+        this.notify();
+    }
+}
+//# sourceMappingURL=bridge-scope.js.map

package/lib/types/client/bridge-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge-scope.js","sourceRoot":"","sources":["../../../src/client/bridge-scope.ts"],"names":[],"mappings":"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"}

package/lib/types/client/compat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compat.d.ts","sourceRoot":"","sources":["../../../src/client/compat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAEnE;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,WAAW,IAAI;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE;YAAE,SAAS,CAAC,EAAE,MAAM,CAAA;SAAE,GAAG,SAAS,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAA;IAC/F,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;IAC3C,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAClD;AAED,kEAAkE;AAClE,MAAM,WAAW,iBAAiB;IAChC,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAA;IACjB,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAA;IACb,oBAAoB;IACpB,KAAK,EAAE,OAAO,CAAA;IACd;gFAC4E;IAC5E,OAAO,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAA;CAC5C;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAevF;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,YAAY,EAAE;IAAE,KAAK,EAAE;QAAE,GAAG,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAA;KAAE,CAAA;CAAE,EACxD,IAAI,EAAE,OAAO,GACZ,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CASxB"}
+{"version":3,"file":"compat.d.ts","sourceRoot":"","sources":["../../../src/client/compat.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAEnE;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,WAAW,IAAI;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE;YAAE,SAAS,CAAC,EAAE,MAAM,CAAA;SAAE,GAAG,SAAS,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAA;IAC/F,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;IAC3C,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAClD;AAED,kEAAkE;AAClE,MAAM,WAAW,iBAAiB;IAChC,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAA;IACjB,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAA;IACb,oBAAoB;IACpB,KAAK,EAAE,OAAO,CAAA;IACd;gFAC4E;IAC5E,OAAO,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAA;CAC5C;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,aAAa,EAAE,IAAI,EAAE,iBAAiB,GAAG,IAAI,CAyBvF;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CACzB,YAAY,EAAE;IAAE,KAAK,EAAE;QAAE,GAAG,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAA;KAAE,CAAA;CAAE,EACxD,IAAI,EAAE,OAAO,GACZ,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CASxB"}

package/lib/types/client/compat.js

@@ -7,17 +7,27 @@
  * as the family tab's slot-inject when the family holder is absent).
  */
 export function registerSettingsFaces(ctx, deps) {
+    // cordis inject 回调收到的是 (ctx, config)——服务要按名从 scope 对象上读
+    // （thinking-levels 腰的同款形态；0.7.1 曾把参数当裸服务 .get/.bind 调用，
+    // 每一代宿主上都是 TypeError，纤维暗死 → onScope 永不回调 → 卡永远降级）。
+    const scopeInject = ctx.inject;
     // Modern hosts (0.1.7+): configForms owns cross-entry durable writes.
-    ctx.inject(['configForms'], (configForms) => {
-        const scope = configForms.get(deps.namespace);
-        void scope.set(deps.field, deps.value);
-        deps.onScope(scope);
+    scopeInject(['configForms'], (scope) => {
+        const forms = scope.configForms;
+        if (forms === undefined)
+            return;
+        const handle = forms.get(deps.namespace);
+        void handle.set(deps.field, deps.value);
+        deps.onScope(handle);
     });
     // Old hosts (≤0.1.5): namespaced durable scope via bind().
-    ctx.inject(['settingsScope'], (settingsScope) => {
-        const scope = settingsScope.bind({ namespace: deps.namespace });
-        void scope.set(deps.field, deps.value);
-        deps.onScope(scope);
+    scopeInject(['settingsScope'], (scope) => {
+        const settingsScope = scope.settingsScope;
+        if (settingsScope === undefined)
+            return;
+        const handle = settingsScope.bind({ namespace: deps.namespace });
+        void handle.set(deps.field, deps.value);
+        deps.onScope(handle);
     });
 }
 /**

package/lib/types/client/compat.js.map

@@ -1 +1 @@
-{"version":3,"file":"compat.js","sourceRoot":"","sources":["../../../src/client/compat.ts"],"names":[],"mappings":"AA6CA;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAkB,EAAE,IAAuB;IAC/E,sEAAsE;IACtE,GAAG,CAAC,MAAM,CAAC,CAAC,aAAa,CAAC,EAAE,CAAC,WAAoB,EAAE,EAAE;QACnD,MAAM,KAAK,GAAI,WAA6D,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;QAChG,KAAK,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAA;QACtC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;IACrB,CAAC,CAAC,CAAA;IACF,2DAA2D;IAC3D,GAAG,CAAC,MAAM,CAAC,CAAC,eAAe,CAAC,EAAE,CAAC,aAAsB,EAAE,EAAE;QACvD,MAAM,KAAK,GAAI,aAEb,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAA;QACtC,KAAK,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAA;QACtC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAA;IACrB,CAAC,CAAC,CAAA;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CACzB,YAAwD,EACxD,IAAa;IAEb,OAAO,CAAC,IAAY,EAAE,EAAE;QACtB,MAAM,GAAG,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAGtC,CAAA;QACD,IAAI,OAAO,GAAG,CAAC,QAAQ,KAAK,UAAU;YAAE,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;;YACrD,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAA;IAClC,CAAC,CAAA;AACH,CAAC"}
+{"version":3,"file":"compat.js","sourceRoot":"","sources":["../../../src/client/compat.ts"],"names":[],"mappings":"AA6CA;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,GAAkB,EAAE,IAAuB;IAC/E,wDAAwD;IACxD,wDAAwD;IACxD,mDAAmD;IACnD,MAAM,WAAW,GAAI,GAEnB,CAAC,MAAM,CAAA;IACT,sEAAsE;IACtE,WAAW,CAAC,CAAC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE;QACrC,MAAM,KAAK,GAAG,KAAK,CAAC,WAAwE,CAAA;QAC5F,IAAI,KAAK,KAAK,SAAS;YAAE,OAAM;QAC/B,MAAM,MAAM,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;QACxC,KAAK,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAA;QACvC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;IACtB,CAAC,CAAC,CAAA;IACF,2DAA2D;IAC3D,WAAW,CAAC,CAAC,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE;QACvC,MAAM,aAAa,GAAG,KAAK,CAAC,aAEf,CAAA;QACb,IAAI,aAAa,KAAK,SAAS;YAAE,OAAM;QACvC,MAAM,MAAM,GAAG,aAAa,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAA;QAChE,KAAK,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,CAAA;QACvC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAA;IACtB,CAAC,CAAC,CAAA;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CACzB,YAAwD,EACxD,IAAa;IAEb,OAAO,CAAC,IAAY,EAAE,EAAE;QACtB,MAAM,GAAG,GAAG,YAAY,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAGtC,CAAA;QACD,IAAI,OAAO,GAAG,CAAC,QAAQ,KAAK,UAAU;YAAE,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;;YACrD,GAAG,CAAC,OAAO,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAA;IAClC,CAAC,CAAA;AACH,CAAC"}

package/lib/types/client/family-card.d.ts

@@ -22,7 +22,8 @@ export interface FamilyCardScope {
     subscribe(listener: () => void): () => void;
 }
 export interface FamilyCardProps {
-    scope: FamilyCardScope;
+    /** 活引用：≤0.1.5 settingsScope 永不 resolve 时保持 undefined（降级渲染）。 */
+    scope?: FamilyCardScope;
     t?: (key: string, params?: Record<string, unknown>) => string;
 }
 export declare function InputTrafficFamilyCard({ scope, t }: FamilyCardProps): JSX.Element;

package/lib/types/client/family-card.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"family-card.d.ts","sourceRoot":"","sources":["../../../src/client/family-card.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAA2D,KAAK,GAAG,EAAE,MAAM,OAAO,CAAA;AAEzF,qCAAqC;AACrC,MAAM,WAAW,eAAe;IAC9B,WAAW,IAAI;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE;YAAE,SAAS,CAAC,EAAE,MAAM,CAAA;SAAE,GAAG,SAAS,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAA;IAC/F,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;CAC5C;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,eAAe,CAAA;IACtB,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAA;CAC9D;AAMD,wBAAgB,sBAAsB,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,eAAe,GAAG,GAAG,CAAC,OAAO,CAcjF"}
+{"version":3,"file":"family-card.d.ts","sourceRoot":"","sources":["../../../src/client/family-card.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAA2D,KAAK,GAAG,EAAE,MAAM,OAAO,CAAA;AAEzF,qCAAqC;AACrC,MAAM,WAAW,eAAe;IAC9B,WAAW,IAAI;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE;YAAE,SAAS,CAAC,EAAE,MAAM,CAAA;SAAE,GAAG,SAAS,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAA;IAC/F,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAA;CAC5C;AAED,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,KAAK,CAAC,EAAE,eAAe,CAAA;IACvB,CAAC,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAA;CAC9D;AASD,wBAAgB,sBAAsB,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,eAAe,GAAG,GAAG,CAAC,OAAO,CAwBjF"}

package/lib/types/client/family-card.js

@@ -13,10 +13,20 @@ import { createElement, useSyncExternalStore } from 'react';
 const row = { display: 'flex', alignItems: 'center', justifyContent: 'space-between', gap: 12, padding: '8px 0', fontSize: 13 };
 const label = { color: 'var(--dsw-alias-label-primary, inherit)' };
 const dim = { color: 'var(--dsw-alias-label-tertiary, rgba(127,127,127,.8))', fontSize: 12, lineHeight: 1.5 };
+/** 无 scope 时的降级快照（模块级常量：useSyncExternalStore 要求稳定引用）。 */
+const DEGRADED_SNAPSHOT = { status: 'unavailable', value: undefined, writable: false };
 export function InputTrafficFamilyCard({ scope, t }) {
-    const snapshot = useSyncExternalStore((listener) => scope.subscribe(listener), () => scope.getSnapshot());
-    const pinned = snapshot.value?.busyEnter ?? 'queue';
+    // hooks 无条件调用（rules-of-hooks）：无 scope 时订阅为 no-op、快照取模块级
+    // 降级常量；scope 缺席与否在挂载期内是稳定的（双轨后 scope 恒有，本分支只
+    // 是防御位），不会触发 hook 序翻转。
+    const snapshot = useSyncExternalStore((listener) => scope?.subscribe(listener) ?? (() => { }), () => scope?.getSnapshot() ?? DEGRADED_SNAPSHOT);
     const tr = (key) => (t ? t(key) : FALLBACK_ZH[key] ?? key);
+    // scope 缺席（防御位，双轨后常态不可达）的降级态：卡仍在账本里
+    // （导航/接管节可见），数据缺席呈现不可用说明而不是崩/空白。
+    if (!scope) {
+        return createElement('div', { style: { display: 'grid', gap: 6 } }, createElement('p', { style: { ...dim, margin: 0 } }, `${tr('family.desc')}（当前宿主设置服务不可用 — 只读）`));
+    }
+    const pinned = snapshot.value?.busyEnter ?? 'queue';
     return createElement('div', { style: { display: 'grid', gap: 6 } }, createElement('div', { style: row }, createElement('span', { style: label }, tr('family.busyEnter')), createElement('span', { style: dim }, `busyEnter = ${pinned}`)), createElement('p', { style: { ...dim, margin: 0 } }, tr('family.desc')));
 }
 /** 无 locale 服务时的中文兜底（与 zh 字典键一一对应）。 */

package/lib/types/client/family-card.js.map

@@ -1 +1 @@
-{"version":3,"file":"family-card.js","sourceRoot":"","sources":["../../../src/client/family-card.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAgC,MAAM,OAAO,CAAA;AAazF,MAAM,GAAG,GAAkB,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,cAAc,EAAE,eAAe,EAAE,GAAG,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAA;AAC9I,MAAM,KAAK,GAAkB,EAAE,KAAK,EAAE,yCAAyC,EAAE,CAAA;AACjF,MAAM,GAAG,GAAkB,EAAE,KAAK,EAAE,uDAAuD,EAAE,QAAQ,EAAE,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE,CAAA;AAE5H,MAAM,UAAU,sBAAsB,CAAC,EAAE,KAAK,EAAE,CAAC,EAAmB;IAClE,MAAM,QAAQ,GAAG,oBAAoB,CACnC,CAAC,QAAQ,EAAE,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,QAAQ,CAAC,EACvC,GAAG,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,CAC1B,CAAA;IACD,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,OAAO,CAAA;IACnD,MAAM,EAAE,GAAG,CAAC,GAAW,EAAU,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAA;IAC1E,OAAO,aAAa,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,EAChE,aAAa,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,EACjC,aAAa,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,kBAAkB,CAAC,CAAC,EAC/D,aAAa,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,eAAe,MAAM,EAAE,CAAC,CAC/D,EACD,aAAa,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,EAAE,GAAG,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,CACxE,CAAA;AACH,CAAC;AAED,uCAAuC;AACvC,MAAM,WAAW,GAA2B;IAC1C,kBAAkB,EAAE,sBAAsB;IAC1C,aAAa,EAAE,gEAAgE;CAChF,CAAA"}
+{"version":3,"file":"family-card.js","sourceRoot":"","sources":["../../../src/client/family-card.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAgC,MAAM,OAAO,CAAA;AAczF,MAAM,GAAG,GAAkB,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,QAAQ,EAAE,cAAc,EAAE,eAAe,EAAE,GAAG,EAAE,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAA;AAC9I,MAAM,KAAK,GAAkB,EAAE,KAAK,EAAE,yCAAyC,EAAE,CAAA;AACjF,MAAM,GAAG,GAAkB,EAAE,KAAK,EAAE,uDAAuD,EAAE,QAAQ,EAAE,EAAE,EAAE,UAAU,EAAE,GAAG,EAAE,CAAA;AAE5H,yDAAyD;AACzD,MAAM,iBAAiB,GAAG,EAAE,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAA;AAEtF,MAAM,UAAU,sBAAsB,CAAC,EAAE,KAAK,EAAE,CAAC,EAAmB;IAClE,wDAAwD;IACxD,6CAA6C;IAC7C,uBAAuB;IACvB,MAAM,QAAQ,GAAG,oBAAoB,CACnC,CAAC,QAAQ,EAAE,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,EACtD,GAAG,EAAE,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,iBAAiB,CAChD,CAAA;IACD,MAAM,EAAE,GAAG,CAAC,GAAW,EAAU,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,CAAA;IAC1E,oCAAoC;IACpC,iCAAiC;IACjC,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,aAAa,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,EAChE,aAAa,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,EAAE,GAAG,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,aAAa,CAAC,oBAAoB,CAAC,CAC/F,CAAA;IACH,CAAC;IACD,MAAM,MAAM,GAAG,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,OAAO,CAAA;IACnD,OAAO,aAAa,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,EAChE,aAAa,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,EACjC,aAAa,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,kBAAkB,CAAC,CAAC,EAC/D,aAAa,CAAC,MAAM,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,EAAE,eAAe,MAAM,EAAE,CAAC,CAC/D,EACD,aAAa,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,EAAE,GAAG,GAAG,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,aAAa,CAAC,CAAC,CACxE,CAAA;AACH,CAAC;AAED,uCAAuC;AACvC,MAAM,WAAW,GAA2B;IAC1C,kBAAkB,EAAE,sBAAsB;IAC1C,aAAa,EAAE,gEAAgE;CAChF,CAAA"}

package/lib/types/client/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,KAAK,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAmBnE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,OAAO,CAAA;AAkBpC;;;;;;GAMG;AACH,eAAO,MAAM,MAAM,UAAkD,CAAA;AAErE;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,CAgG9C"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,OAAO,KAAK,EAAE,OAAO,IAAI,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAoBnE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,gBAAgB,OAAO,CAAA;AAkBpC;;;;;;GAMG;AACH,eAAO,MAAM,MAAM,UAAkD,CAAA;AAErE;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,CA0H9C"}