pyric 0.1.0-alpha.21 → 0.1.0-alpha.24

package/dist/sandbox/admin-firestore/remote/listeners.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"listeners.d.ts","sourceRoot":"","sources":["../../../../src/sandbox/admin-firestore/remote/listeners.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAUH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAA8B,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE9E;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,EAAE,OAAO,MAE9C,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,CACpC,OAAO,EAAE;IAAE,sBAAsB,CAAC,EAAE,OAAO,CAAA;CAAE,EAC7C,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,SAAS,EACjD,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,SAAS,KAC5C,MAAM,IAAI,CAAC;AAEhB,wEAAwE;AACxE,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,OAAO,GAAG,uBAAuB,GAAG,SAAS,CAI5F;AAED;;;;;;GAMG;AACH,KAAK,cAAc,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,MAAM,IAAI,CAAC;AAGvE,wBAAgB,4BAA4B,CAAC,EAAE,EAAE,cAAc,GAAG,IAAI,CAErE;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,IAAI,CAQjF;AAED;;;;sEAIsE;AACtE,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,SAAS,EACd,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE;IAAE,sBAAsB,CAAC,EAAE,OAAO,CAAA;CAAE,EAC7C,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,SAAS,EACjD,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,SAAS,GAC9C,MAAM,IAAI,CAkDZ"}
+{"version":3,"file":"listeners.d.ts","sourceRoot":"","sources":["../../../../src/sandbox/admin-firestore/remote/listeners.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAUH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,KAAK,EAA8B,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE9E;;;;;;;GAOG;AACH,eAAO,MAAM,yBAAyB,EAAE,OAAO,MAE9C,CAAC;AAEF,MAAM,MAAM,uBAAuB,GAAG,CACpC,OAAO,EAAE;IAAE,sBAAsB,CAAC,EAAE,OAAO,CAAA;CAAE,EAC7C,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,SAAS,EACjD,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,SAAS,KAC5C,MAAM,IAAI,CAAC;AAEhB,wEAAwE;AACxE,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,OAAO,GAAG,uBAAuB,GAAG,SAAS,CAI5F;AAED;;;;;;GAMG;AACH,KAAK,cAAc,GAAG,CAAC,GAAG,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,MAAM,IAAI,CAAC;AAGvE,wBAAgB,4BAA4B,CAAC,EAAE,EAAE,cAAc,GAAG,IAAI,CAErE;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,IAAI,CAQjF;AAED;;;;sEAIsE;AACtE,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,SAAS,EACd,MAAM,EAAE,UAAU,EAClB,OAAO,EAAE;IAAE,sBAAsB,CAAC,EAAE,OAAO,CAAA;CAAE,EAC7C,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,SAAS,EACjD,OAAO,EAAE,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,SAAS,GAC9C,MAAM,IAAI,CA4DZ"}

package/dist/sandbox/admin-firestore/remote/listeners.js

@@ -45,45 +45,66 @@ export function registerRemoteListener(arm, target, options, onNext, onError) {
     // Previous query rows, kept so `docChanges()` diffs across fires the
     // same way the local listener path does.
     let prevDocs;
+    function reportError(error) {
+        const translated = toRemoteSandboxError(error);
+        const hasErrorCallback = onError !== undefined;
+        if (hasErrorCallback)
+            onError(translated);
+        else
+            console.error('pyric remote Firestore: uncaught onSnapshot error:', translated);
+    }
     let detach;
     try {
         detach = arm.sandbox.channel.subscribe({ target, actAs: arm.lens }, (value) => {
-            if (!onNext)
+            const hasNoCallback = onNext === undefined;
+            if (hasNoCallback)
                 return;
-            const snap = value;
-            if (Array.isArray(snap.docs)) {
-                // Query fire. `buildQuerySnapshot` translates the internal-form
-                // data to compat shapes itself, so decode WITHOUT translation.
-                const docList = snap.docs.map((row) => ({
-                    path: row.path ?? row.id,
-                    data: row.data ? decodeInternal(row.data) : {},
-                }));
-                const queryPath = target.__ref === 'query'
-                    ? (target.source.__ref === 'group' ? target.source.collectionId : target.source.path)
-                    : target.__ref === 'group'
-                        ? target.collectionId
-                        : target.path;
-                const querySnap = buildQuerySnapshot({ path: queryPath }, docList, { excludesMetadataChanges }, prevDocs);
-                prevDocs = docList;
-                onNext(querySnap);
+            let decoded;
+            try {
+                const snap = value;
+                const documents = snap.docs;
+                const isQuery = Array.isArray(documents);
+                if (isQuery) {
+                    const docList = documents.map((row) => {
+                        const data = row.data;
+                        const hasData = data !== undefined;
+                        return { path: row.path ?? row.id, data: hasData ? decodeInternal(data) : {} };
+                    });
+                    decoded = buildQuerySnapshot({ path: listenerTargetPath(target) }, docList, { excludesMetadataChanges }, prevDocs);
+                    prevDocs = docList;
+                }
+                else {
+                    const id = snap.id;
+                    const isDocument = typeof id === 'string';
+                    if (isDocument) {
+                        const path = snap.path ?? id;
+                        const serialized = snap.data;
+                        const hasData = snap.exists === true && serialized !== undefined;
+                        const data = hasData ? decodeInternal(serialized) : null;
+                        decoded = buildDocumentSnapshot(path, data);
+                    }
+                }
             }
-            else if (typeof snap.id === 'string') {
-                // Doc fire.
-                const path = snap.path ?? snap.id;
-                const data = snap.exists && snap.data ? decodeInternal(snap.data) : null;
-                onNext(buildDocumentSnapshot(path, data));
+            catch (error) {
+                detach();
+                reportError(error);
+                return;
             }
-        }, (err) => {
-            const translated = toRemoteSandboxError(err);
-            if (onError)
-                onError(translated);
-            else
-                console.error('pyric remote Firestore: uncaught onSnapshot error:', translated);
-        });
+            const hasSnapshot = decoded !== undefined;
+            if (hasSnapshot)
+                onNext(decoded);
+        }, reportError);
     }
     catch (e) {
         throw toRemoteSandboxError(e);
     }
     return detach;
 }
+function listenerTargetPath(target) {
+    switch (target.__ref) {
+        case 'query': return listenerTargetPath(target.source);
+        case 'group': return target.collectionId;
+        default: return target.path;
+    }
+}
 //# sourceMappingURL=listeners.js.map

package/dist/sandbox/admin-firestore/remote/listeners.js.map

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

package/dist/sandbox/admin-firestore/remote/value-codec.d.ts

@@ -10,22 +10,15 @@
  * the worker STORES real typed values (rules comparisons and `orderBy`
  * see a Timestamp, not a map). Read payloads arrive as the
  * `SerializedDocData` JSON envelope and are rehydrated with the ONE shared
- * codec (`pyric/firestore/internal/value-codec`'s `rehydrateDocValue`) then
+ * codec (`pyric/firestore/internal/value-codec`) under the reply's encoding, then
  * translated to
  * the compat field shapes (`translateReadData`) — the same shapes the
  * local arm's read path yields.
  *
- * KNOWN CODEC DIVERGENCE (accepted): user data that happens to be SHAPED
- * like a codec marker — a plain map such as `{ __type: 'timestamp',
- * seconds, nanos }` or `{ type: 'firestore/timestamp/1.0', … }` — is
- * TRANSMUTED into the real typed value on the relayed path (the host's
- * `prepareWriteData` / constraint rehydration cannot tell an intentional
- * marker from a lookalike), while an in-page `setDoc` of the same map
- * stores a plain map. This is the persistence codec's own behavior (an
- * IndexedDB save/reload transmutes the same shapes), so the relay is
- * consistent with the sandbox's durability semantics rather than with
- * the in-page live path — marker-shaped user data is already reserved
- * vocabulary in this system.
+ * Legacy remote writes still reserve scalar-marker shapes. They do not yet
+ * declare the newer map-safe value encoding. Reads honor the returned
+ * envelope's encoding through the shared codec. Adopting explicit encoding
+ * for remote writes and migrating persistence remain required work.
  */
 import { type DocumentData } from 'pyric/sandbox/admin-compat';
 import type { WireDocData } from './wire-types.js';

package/dist/sandbox/admin-firestore/remote/value-codec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"value-codec.d.ts","sourceRoot":"","sources":["../../../../src/sandbox/admin-firestore/remote/value-codec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,EAEL,KAAK,YAAY,EAElB,MAAM,4BAA4B,CAAC;AAGpC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAsCnD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CA0B/C;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAE3D;AAID;;iEAEiE;AACjE,wBAAgB,cAAc,CAAC,UAAU,EAAE,WAAW,GAAG,YAAY,CAEpE;AAED;;iEAEiE;AACjE,wBAAgB,aAAa,CAAC,UAAU,EAAE,WAAW,GAAG,YAAY,CAEnE"}
+{"version":3,"file":"value-codec.d.ts","sourceRoot":"","sources":["../../../../src/sandbox/admin-firestore/remote/value-codec.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,EAEL,KAAK,YAAY,EAElB,MAAM,4BAA4B,CAAC;AAGpC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAsCnD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,GAAG,OAAO,CA0B/C;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAE3D;AAID;;iEAEiE;AACjE,wBAAgB,cAAc,CAAC,UAAU,EAAE,WAAW,GAAG,YAAY,CAEpE;AAED;;iEAEiE;AACjE,wBAAgB,aAAa,CAAC,UAAU,EAAE,WAAW,GAAG,YAAY,CAEnE"}

package/dist/sandbox/admin-firestore/remote/value-codec.js

@@ -10,24 +10,17 @@
  * the worker STORES real typed values (rules comparisons and `orderBy`
  * see a Timestamp, not a map). Read payloads arrive as the
  * `SerializedDocData` JSON envelope and are rehydrated with the ONE shared
- * codec (`pyric/firestore/internal/value-codec`'s `rehydrateDocValue`) then
+ * codec (`pyric/firestore/internal/value-codec`) under the reply's encoding, then
  * translated to
  * the compat field shapes (`translateReadData`) — the same shapes the
  * local arm's read path yields.
  *
- * KNOWN CODEC DIVERGENCE (accepted): user data that happens to be SHAPED
- * like a codec marker — a plain map such as `{ __type: 'timestamp',
- * seconds, nanos }` or `{ type: 'firestore/timestamp/1.0', … }` — is
- * TRANSMUTED into the real typed value on the relayed path (the host's
- * `prepareWriteData` / constraint rehydration cannot tell an intentional
- * marker from a lookalike), while an in-page `setDoc` of the same map
- * stores a plain map. This is the persistence codec's own behavior (an
- * IndexedDB save/reload transmutes the same shapes), so the relay is
- * consistent with the sandbox's durability semantics rather than with
- * the in-page live path — marker-shaped user data is already reserved
- * vocabulary in this system.
+ * Legacy remote writes still reserve scalar-marker shapes. They do not yet
+ * declare the newer map-safe value encoding. Reads honor the returned
+ * envelope's encoding through the shared codec. Adopting explicit encoding
+ * for remote writes and migrating persistence remain required work.
  */
-import { rehydrateDocValue } from 'pyric/firestore/internal/value-codec';
+import { rehydrateEncodedDocValue } from 'pyric/firestore/internal/value-codec';
 import { Timestamp as CompatTimestamp, } from 'pyric/sandbox/admin-compat';
 import { translateReadData } from '../../../firestore/sandbox/admin-compat/read-translation.js';
 import { invalidArgument } from './errors.js';
@@ -110,7 +103,7 @@ export function encodeWriteData(data) {
  *  their RULES-INTERNAL wrapper form (what the local engine stores). Used
  *  where a downstream helper does its own compat translation. */
 export function decodeInternal(serialized) {
-    return rehydrateDocValue(JSON.parse(serialized.json));
+    return rehydrateEncodedDocValue(JSON.parse(serialized.json), serialized.valueEncoding);
 }
 /** Full read-path decode: shared codec rehydration + the same
  *  internal→compat field-shape translation the local arm applies

package/dist/sandbox/admin-firestore/remote/value-codec.js.map

@@ -1 +1 @@
-{"version":3,"file":"value-codec.js","sourceRoot":"","sources":["../../../../src/sandbox/admin-firestore/remote/value-codec.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"value-codec.js","sourceRoot":"","sources":["../../../../src/sandbox/admin-firestore/remote/value-codec.ts"],"names":[],"mappings":"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"}

package/dist/sandbox/admin-firestore/remote/wire-types.d.ts

@@ -4,6 +4,7 @@
  * because `pyric` cannot depend on `@pyric/cli`; ops are kept
  * structurally identical to `packages/cli/src/serve/worker/protocol.ts`.
  */
+import type { DocValueEncoding } from 'pyric/firestore/internal/value-codec';
 /** Wire form of a doc/collection/group/query target. Mirrors
  *  `@pyric/cli`' `TargetDescriptor` — plain JSON, spelled loosely here
  *  because `pyric` cannot import the protocol module. */
@@ -84,6 +85,7 @@ export type WireWrite = {
 };
 /** Mirrors the protocol's `SerializedDocData` — the JSON string envelope. */
 export interface WireDocData {
+    valueEncoding?: DocValueEncoding;
     json: string;
 }
 /** Mirrors the protocol's `TxnReadEntry`. `data` is the worker's ORIGINAL

package/dist/sandbox/admin-firestore/remote/wire-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wire-types.d.ts","sourceRoot":"","sources":["../../../../src/sandbox/admin-firestore/remote/wire-types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"wire-types.d.ts","sourceRoot":"","sources":["../../../../src/sandbox/admin-firestore/remote/wire-types.ts"],"names":[],"mappings":"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"}

package/dist/sandbox/attribution/attribution-mode.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The switch that decides whether listener attribution runs.
+ *
+ * Attribution is a development diagnostic: it constructs one `Error` per
+ * listener attach to read a stack, and installs one `MutationObserver` around
+ * each snapshot callback. Neither cost belongs in a production build, and
+ * neither result has a consumer there, so attribution is off whenever the
+ * environment says production.
+ *
+ * Two production signals are read, in this order, because the mirror runs in
+ * two runtimes:
+ *
+ * 1. `import.meta.env.PROD`, which a browser bundler substitutes at build
+ *    time. This is the signal that survives into a shipped bundle, where no
+ *    `process` exists.
+ * 2. `process.env.NODE_ENV === 'production'`, the marker the rest of this
+ *    repository already treats as "this is production" (the CLI's Next.js
+ *    passthrough guard and the `@pyric/cli/register` refusal both read it).
+ *
+ * A caller that wants attribution regardless of either signal turns it on
+ * explicitly through {@link configureListenerAttribution}, which overrides
+ * both. That is the "explicit option" path: a production-mode test harness, or
+ * a host that wants attribution in a build the bundler marked production.
+ */
+/**
+ * How the switch decides. `'auto'` reads the environment; `'on'` and `'off'`
+ * are explicit caller overrides that ignore it.
+ */
+export type ListenerAttributionMode = 'auto' | 'on' | 'off';
+/** Override the environment decision. Pass `'auto'` to hand it back. */
+export declare function configureListenerAttribution(next: ListenerAttributionMode): void;
+/** The override currently in force. `'auto'` means the environment decides. */
+export declare function listenerAttributionMode(): ListenerAttributionMode;
+/** Whether listener attribution should run right now. */
+export declare function listenerAttributionEnabled(): boolean;
+//# sourceMappingURL=attribution-mode.d.ts.map

package/dist/sandbox/attribution/attribution-mode.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribution-mode.d.ts","sourceRoot":"","sources":["../../../src/sandbox/attribution/attribution-mode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAIH;;;GAGG;AACH,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,IAAI,GAAG,KAAK,CAAC;AAI5D,wEAAwE;AACxE,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,uBAAuB,GAAG,IAAI,CAEhF;AAED,+EAA+E;AAC/E,wBAAgB,uBAAuB,IAAI,uBAAuB,CAEjE;AAuBD,yDAAyD;AACzD,wBAAgB,0BAA0B,IAAI,OAAO,CAMpD"}

package/dist/sandbox/attribution/attribution-mode.js

@@ -0,0 +1,68 @@
+/**
+ * The switch that decides whether listener attribution runs.
+ *
+ * Attribution is a development diagnostic: it constructs one `Error` per
+ * listener attach to read a stack, and installs one `MutationObserver` around
+ * each snapshot callback. Neither cost belongs in a production build, and
+ * neither result has a consumer there, so attribution is off whenever the
+ * environment says production.
+ *
+ * Two production signals are read, in this order, because the mirror runs in
+ * two runtimes:
+ *
+ * 1. `import.meta.env.PROD`, which a browser bundler substitutes at build
+ *    time. This is the signal that survives into a shipped bundle, where no
+ *    `process` exists.
+ * 2. `process.env.NODE_ENV === 'production'`, the marker the rest of this
+ *    repository already treats as "this is production" (the CLI's Next.js
+ *    passthrough guard and the `@pyric/cli/register` refusal both read it).
+ *
+ * A caller that wants attribution regardless of either signal turns it on
+ * explicitly through {@link configureListenerAttribution}, which overrides
+ * both. That is the "explicit option" path: a production-mode test harness, or
+ * a host that wants attribution in a build the bundler marked production.
+ */
+const PRODUCTION_ENVIRONMENT = 'production';
+let mode = 'auto';
+/** Override the environment decision. Pass `'auto'` to hand it back. */
+export function configureListenerAttribution(next) {
+    mode = next;
+}
+/** The override currently in force. `'auto'` means the environment decides. */
+export function listenerAttributionMode() {
+    return mode;
+}
+/**
+ * `true` when the bundler stamped this build as production. Read through a
+ * cast and a try/catch because `import.meta.env` exists only under a bundler,
+ * and a plain Node ESM runtime leaves it undefined.
+ */
+function isBundledProduction() {
+    try {
+        const env = import.meta.env;
+        return env?.PROD === true;
+    }
+    catch {
+        return false;
+    }
+}
+/** `true` when the host process declares itself production. */
+function isProcessProduction() {
+    const runtime = globalThis.process;
+    if (runtime === undefined)
+        return false;
+    return runtime.env?.NODE_ENV === PRODUCTION_ENVIRONMENT;
+}
+/** Whether listener attribution should run right now. */
+export function listenerAttributionEnabled() {
+    if (mode === 'on')
+        return true;
+    if (mode === 'off')
+        return false;
+    if (isBundledProduction())
+        return false;
+    if (isProcessProduction())
+        return false;
+    return true;
+}
+//# sourceMappingURL=attribution-mode.js.map

package/dist/sandbox/attribution/attribution-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attribution-mode.js","sourceRoot":"","sources":["../../../src/sandbox/attribution/attribution-mode.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,MAAM,sBAAsB,GAAG,YAAY,CAAC;AAQ5C,IAAI,IAAI,GAA4B,MAAM,CAAC;AAE3C,wEAAwE;AACxE,MAAM,UAAU,4BAA4B,CAAC,IAA6B;IACxE,IAAI,GAAG,IAAI,CAAC;AACd,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,uBAAuB;IACrC,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,SAAS,mBAAmB;IAC1B,IAAI,CAAC;QACH,MAAM,GAAG,GAAI,MAAM,CAAC,IAAqC,CAAC,GAAG,CAAC;QAC9D,OAAO,GAAG,EAAE,IAAI,KAAK,IAAI,CAAC;IAC5B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,+DAA+D;AAC/D,SAAS,mBAAmB;IAC1B,MAAM,OAAO,GAAI,UAAyE,CAAC,OAAO,CAAC;IACnG,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IACxC,OAAO,OAAO,CAAC,GAAG,EAAE,QAAQ,KAAK,sBAAsB,CAAC;AAC1D,CAAC;AAED,yDAAyD;AACzD,MAAM,UAAU,0BAA0B;IACxC,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAC/B,IAAI,IAAI,KAAK,KAAK;QAAE,OAAO,KAAK,CAAC;IACjC,IAAI,mBAAmB,EAAE;QAAE,OAAO,KAAK,CAAC;IACxC,IAAI,mBAAmB,EAAE;QAAE,OAAO,KAAK,CAAC;IACxC,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/sandbox/attribution/effect-regions.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Attributing a snapshot delivery to the part of the page it changed.
+ *
+ * The window is the SYNCHRONOUS run of the application's snapshot callback,
+ * and nothing else. `MutationObserver` is started immediately before the
+ * callback, drained with `takeRecords()` immediately after it returns, and
+ * disconnected. There is no debounce, no timer, and no microtask wait.
+ *
+ * That is deliberate, and it is also the limit of what this owner kind can
+ * claim. A callback that writes into a framework's state rather than into the
+ * DOM renders LATER, on the framework's own schedule, outside this window, so
+ * this owner sees nothing for it. Waiting longer would not fix that: it would
+ * start attributing unrelated renders that happened to land in the same
+ * interval, which is worse than reporting nothing. Listeners whose effects are
+ * mediated by a framework are attributed by their creation `frame` and by the
+ * `owner` tag instead, which is exactly why both exist.
+ *
+ * Outside a browser there is no `MutationObserver` and no `document`, so this
+ * is a pure pass-through and the delivery carries no regions.
+ */
+import type { ListenerOwner } from '../types/events.js';
+/**
+ * Run `run` and report which elements it mutated, as a `regions` owner.
+ *
+ * Anything `run` throws propagates unchanged, after the observer is torn down:
+ * attribution never changes what a callback does or what its caller sees.
+ */
+export declare function recordEffectRegions(run: () => void): ListenerOwner | undefined;
+/**
+ * Reduce mutation records to a de-duplicated, source-ordered selector list.
+ * Exported for the test, which builds records directly.
+ */
+export declare function regionsFromRecords(records: ReadonlyArray<{
+    target?: unknown;
+    addedNodes?: ArrayLike<unknown>;
+}>): ListenerOwner | undefined;
+//# sourceMappingURL=effect-regions.d.ts.map

package/dist/sandbox/attribution/effect-regions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"effect-regions.d.ts","sourceRoot":"","sources":["../../../src/sandbox/attribution/effect-regions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAoDxD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,IAAI,GAAG,aAAa,GAAG,SAAS,CAoB9E;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,aAAa,CAAC;IAAE,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,SAAS,CAAC,OAAO,CAAC,CAAA;CAAE,CAAC,GAC5E,aAAa,GAAG,SAAS,CAsB3B"}

package/dist/sandbox/attribution/effect-regions.js

@@ -0,0 +1,114 @@
+/**
+ * Attributing a snapshot delivery to the part of the page it changed.
+ *
+ * The window is the SYNCHRONOUS run of the application's snapshot callback,
+ * and nothing else. `MutationObserver` is started immediately before the
+ * callback, drained with `takeRecords()` immediately after it returns, and
+ * disconnected. There is no debounce, no timer, and no microtask wait.
+ *
+ * That is deliberate, and it is also the limit of what this owner kind can
+ * claim. A callback that writes into a framework's state rather than into the
+ * DOM renders LATER, on the framework's own schedule, outside this window, so
+ * this owner sees nothing for it. Waiting longer would not fix that: it would
+ * start attributing unrelated renders that happened to land in the same
+ * interval, which is worse than reporting nothing. Listeners whose effects are
+ * mediated by a framework are attributed by their creation `frame` and by the
+ * `owner` tag instead, which is exactly why both exist.
+ *
+ * Outside a browser there is no `MutationObserver` and no `document`, so this
+ * is a pure pass-through and the delivery carries no regions.
+ */
+import { listenerAttributionEnabled } from './attribution-mode.js';
+import { isSelectableElement, regionSelectorFor, } from './element-selector.js';
+const OBSERVED_MUTATIONS = {
+    childList: true,
+    attributes: true,
+    characterData: true,
+    subtree: true,
+};
+/** The observer constructor and document to watch, when both are present. */
+function domUnderObservation() {
+    const host = globalThis;
+    const Observer = host.MutationObserver;
+    const doc = host.document;
+    if (typeof Observer !== 'function')
+        return undefined;
+    if (doc === undefined || doc === null)
+        return undefined;
+    return { Observer, document: doc };
+}
+/**
+ * The nearest element a mutated node belongs to. A text node reports its
+ * parent; an element reports itself; anything else is skipped.
+ */
+function nearestElement(node) {
+    if (isSelectableElement(node))
+        return node;
+    if (node === null || typeof node !== 'object')
+        return undefined;
+    const parent = node.parentElement;
+    if (isSelectableElement(parent))
+        return parent;
+    return undefined;
+}
+/**
+ * Run `run` and report which elements it mutated, as a `regions` owner.
+ *
+ * Anything `run` throws propagates unchanged, after the observer is torn down:
+ * attribution never changes what a callback does or what its caller sees.
+ */
+export function recordEffectRegions(run) {
+    if (!listenerAttributionEnabled()) {
+        run();
+        return undefined;
+    }
+    const dom = domUnderObservation();
+    if (dom === undefined) {
+        run();
+        return undefined;
+    }
+    const observer = new dom.Observer(() => { });
+    let records = [];
+    try {
+        observer.observe(dom.document, OBSERVED_MUTATIONS);
+        run();
+    }
+    finally {
+        records = observer.takeRecords();
+        observer.disconnect();
+    }
+    return regionsFromRecords(records);
+}
+/**
+ * Reduce mutation records to a de-duplicated, source-ordered selector list.
+ * Exported for the test, which builds records directly.
+ */
+export function regionsFromRecords(records) {
+    const selectors = [];
+    const seen = new Set();
+    const remember = (node) => {
+        const element = nearestElement(node);
+        if (element === undefined)
+            return;
+        const selector = regionSelectorFor(element);
+        if (selector.length === 0)
+            return;
+        if (seen.has(selector))
+            return;
+        seen.add(selector);
+        selectors.push(selector);
+    };
+    for (const record of records) {
+        remember(record.target);
+        const added = record.addedNodes;
+        if (!added)
+            continue;
+        for (let index = 0; index < added.length; index += 1) {
+            remember(added[index]);
+        }
+    }
+    if (selectors.length === 0)
+        return undefined;
+    return { kind: 'regions', selectors };
+}
+//# sourceMappingURL=effect-regions.js.map

package/dist/sandbox/attribution/effect-regions.js.map

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

package/dist/sandbox/attribution/element-selector.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Turning a DOM element into a string that names it again later.
+ *
+ * Two callers want slightly different things, so this file offers two
+ * entry points over one identity ladder:
+ *
+ * - {@link ownerSelectorFor} is for an element the caller handed to pyric as
+ *   a listener's owner. The caller asked to be identified, so an element with
+ *   no identity of its own is GIVEN one: a generated `data-pyric-owner`
+ *   attribute that survives re-render and makes the selector stable.
+ * - {@link regionSelectorFor} is for an element pyric observed a callback
+ *   mutating. Observation must not change the page, so an element with no
+ *   identity of its own gets a structural path instead of a new attribute.
+ *
+ * Both prefer, in order: the element's `id`, then an existing
+ * `data-pyric-owner`, then their respective fallback.
+ */
+/** The attribute pyric reads, and mints, to name an owning element. */
+export declare const OWNER_ATTRIBUTE = "data-pyric-owner";
+/** The minimal element shape this file needs. Keeps the module DOM-free. */
+export interface SelectableElement {
+    readonly tagName?: string;
+    readonly id?: string;
+    getAttribute(name: string): string | null;
+    setAttribute(name: string, value: string): void;
+    readonly parentElement?: SelectableElement | null;
+    readonly children?: ArrayLike<SelectableElement>;
+}
+/** `true` when `value` responds to the element methods this file calls. */
+export declare function isSelectableElement(value: unknown): value is SelectableElement;
+/** The element's lower-case tag name, or `'element'` when it reports none. */
+export declare function tagNameOf(element: SelectableElement): string;
+/**
+ * Name an element the caller nominated as a listener's owner, minting a
+ * `data-pyric-owner` attribute when it has no identity of its own.
+ */
+export declare function ownerSelectorFor(element: SelectableElement): string;
+/**
+ * Name an element a callback mutated, without writing to the document.
+ */
+export declare function regionSelectorFor(element: SelectableElement): string;
+//# sourceMappingURL=element-selector.d.ts.map

package/dist/sandbox/attribution/element-selector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"element-selector.d.ts","sourceRoot":"","sources":["../../../src/sandbox/attribution/element-selector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,uEAAuE;AACvE,eAAO,MAAM,eAAe,qBAAqB,CAAC;AAIlD,4EAA4E;AAC5E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC1C,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAChD,QAAQ,CAAC,aAAa,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAClD,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC,iBAAiB,CAAC,CAAC;CAClD;AAED,2EAA2E;AAC3E,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAK9E;AAED,8EAA8E;AAC9E,wBAAgB,SAAS,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAI5D;AAmDD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAOnE;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAIpE"}