nucleus-core-ts 0.10.236 → 0.10.237
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/.build-ok +1 -1
- package/dist/nucleus.config.d.ts +1 -0
- package/dist/src/Client/Replay/answers/aliases.d.ts +20 -0
- package/dist/src/Client/Replay/answers/aliases.js +57 -0
- package/dist/src/Client/Replay/answers/factory.d.ts +24 -0
- package/dist/src/Client/Replay/answers/factory.js +97 -0
- package/dist/src/Client/Replay/answers/index.d.ts +2 -0
- package/dist/src/Client/Replay/answers/index.js +2 -0
- package/dist/src/Client/Replay/answers/match.d.ts +34 -0
- package/dist/src/Client/Replay/answers/match.js +33 -0
- package/dist/src/Client/Replay/channel/channel.d.ts +144 -0
- package/dist/src/Client/Replay/channel/channel.js +150 -0
- package/dist/src/Client/Replay/channel/index.d.ts +1 -0
- package/dist/src/Client/Replay/channel/index.js +1 -0
- package/dist/src/Client/Replay/contract/index.d.ts +4 -0
- package/dist/src/Client/Replay/contract/index.js +4 -0
- package/dist/src/Client/Replay/contract/parse.d.ts +12 -0
- package/dist/src/Client/Replay/contract/parse.js +98 -0
- package/dist/src/Client/Replay/contract/schema.d.ts +290 -0
- package/dist/src/Client/Replay/contract/schema.js +256 -0
- package/dist/src/Client/Replay/contract/types.d.ts +197 -0
- package/dist/src/Client/Replay/contract/types.js +10 -0
- package/dist/src/Client/Replay/contract/v1.d.ts +72 -0
- package/dist/src/Client/Replay/contract/v1.js +70 -0
- package/dist/src/Client/Replay/driver/actions.d.ts +27 -0
- package/dist/src/Client/Replay/driver/actions.js +55 -0
- package/dist/src/Client/Replay/driver/choose.d.ts +15 -0
- package/dist/src/Client/Replay/driver/choose.js +46 -0
- package/dist/src/Client/Replay/driver/find.d.ts +44 -0
- package/dist/src/Client/Replay/driver/find.js +109 -0
- package/dist/src/Client/Replay/driver/index.d.ts +5 -0
- package/dist/src/Client/Replay/driver/index.js +5 -0
- package/dist/src/Client/Replay/driver/input.d.ts +21 -0
- package/dist/src/Client/Replay/driver/input.js +120 -0
- package/dist/src/Client/Replay/driver/run.d.ts +30 -0
- package/dist/src/Client/Replay/driver/run.js +66 -0
- package/dist/src/Client/Replay/index.d.ts +7 -0
- package/dist/src/Client/Replay/index.js +7 -0
- package/dist/src/Client/Replay/realm/clock.d.ts +16 -0
- package/dist/src/Client/Replay/realm/clock.js +19 -0
- package/dist/src/Client/Replay/realm/fetchRouter.d.ts +25 -0
- package/dist/src/Client/Replay/realm/fetchRouter.js +46 -0
- package/dist/src/Client/Replay/realm/frame.d.ts +40 -0
- package/dist/src/Client/Replay/realm/frame.js +38 -0
- package/dist/src/Client/Replay/realm/index.d.ts +5 -0
- package/dist/src/Client/Replay/realm/index.js +5 -0
- package/dist/src/Client/Replay/realm/install.d.ts +26 -0
- package/dist/src/Client/Replay/realm/install.js +27 -0
- package/dist/src/Client/Replay/realm/storage.d.ts +14 -0
- package/dist/src/Client/Replay/realm/storage.js +51 -0
- package/dist/src/Client/Replay/streams/delivery.d.ts +9 -0
- package/dist/src/Client/Replay/streams/delivery.js +28 -0
- package/dist/src/Client/Replay/streams/emit.d.ts +16 -0
- package/dist/src/Client/Replay/streams/emit.js +66 -0
- package/dist/src/Client/Replay/streams/eventSource.d.ts +29 -0
- package/dist/src/Client/Replay/streams/eventSource.js +63 -0
- package/dist/src/Client/Replay/streams/index.d.ts +6 -0
- package/dist/src/Client/Replay/streams/index.js +6 -0
- package/dist/src/Client/Replay/streams/path.d.ts +10 -0
- package/dist/src/Client/Replay/streams/path.js +28 -0
- package/dist/src/Client/Replay/streams/schedule.d.ts +17 -0
- package/dist/src/Client/Replay/streams/schedule.js +39 -0
- package/dist/src/Client/Replay/streams/socket.d.ts +36 -0
- package/dist/src/Client/Replay/streams/socket.js +104 -0
- package/dist/src/Client/Replay/streams/sse.d.ts +20 -0
- package/dist/src/Client/Replay/streams/sse.js +65 -0
- package/dist/src/Client/Replay/timeline/clock.d.ts +8 -0
- package/dist/src/Client/Replay/timeline/clock.js +22 -0
- package/dist/src/Client/Replay/timeline/fakeClock.d.ts +7 -0
- package/dist/src/Client/Replay/timeline/fakeClock.js +43 -0
- package/dist/src/Client/Replay/timeline/index.d.ts +3 -0
- package/dist/src/Client/Replay/timeline/index.js +3 -0
- package/dist/src/Client/Replay/timeline/loader.d.ts +20 -0
- package/dist/src/Client/Replay/timeline/loader.js +84 -0
- package/dist/src/Client/Replay/timeline/timeline.d.ts +36 -0
- package/dist/src/Client/Replay/timeline/timeline.js +149 -0
- package/package.json +5 -1
package/dist/.build-ok
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
0.10.
|
|
1
|
+
0.10.237
|
package/dist/nucleus.config.d.ts
CHANGED
|
@@ -26,6 +26,7 @@ export declare const config: {
|
|
|
26
26
|
readonly transpileOnly: {
|
|
27
27
|
readonly './fe': "./fe/index.ts";
|
|
28
28
|
readonly './proxy': "./src/Client/Proxy/index.ts";
|
|
29
|
+
readonly './replay': "./src/Client/Replay/index.ts";
|
|
29
30
|
};
|
|
30
31
|
/** Additional directories to transpile (dependencies of transpileOnly entries) */
|
|
31
32
|
/**
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import type { JsonValue } from '../contract/types';
|
|
2
|
+
export type IdAliases = {
|
|
3
|
+
/** Learns `recorded id -> live id` pairs from a live payload and the recorded payload it is answered with. */
|
|
4
|
+
learn: (live: JsonValue, recorded: JsonValue) => void;
|
|
5
|
+
/** Registers more recorded text (a chapter loaded later), so its ids count as recorded and are never aliased. */
|
|
6
|
+
know: (recordedTexts: readonly string[]) => void;
|
|
7
|
+
/** A live payload written with the recorded ids, so it can be matched against the recorded payloads. */
|
|
8
|
+
toRecorded: (text: string) => string;
|
|
9
|
+
/** A recorded body written with the ids this page generated, so the page recognises its own records. */
|
|
10
|
+
toLive: (text: string) => string;
|
|
11
|
+
};
|
|
12
|
+
/**
|
|
13
|
+
* Pages create some ids in the browser (a new record, a draft, a field) and later check that an answer names the same
|
|
14
|
+
* id. During playback the page draws fresh ids, so a recorded answer would name an id the page never made.
|
|
15
|
+
* An id is aliased only when the live value appears nowhere in the recording: such a value can only have been generated
|
|
16
|
+
* by the page itself, never read from a recorded answer.
|
|
17
|
+
*/
|
|
18
|
+
export declare function createIdAliases(recordedTexts: readonly string[]): IdAliases;
|
|
19
|
+
/** Learns from two payload texts; either may be absent (a call without a payload teaches nothing). */
|
|
20
|
+
export declare function learnFromTexts(aliases: IdAliases, live: string | null, recorded: string | null): void;
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
const uuidPattern = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi;
|
|
2
|
+
const wholeUuid = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
|
|
3
|
+
function replaceIds(text, map) {
|
|
4
|
+
return map.size === 0 ? text : text.replace(uuidPattern, (id)=>map.get(id) ?? id);
|
|
5
|
+
}
|
|
6
|
+
function parse(text) {
|
|
7
|
+
const value = JSON.parse(text);
|
|
8
|
+
return value;
|
|
9
|
+
}
|
|
10
|
+
function idsIn(texts) {
|
|
11
|
+
return texts.flatMap((text)=>text.match(uuidPattern) ?? []);
|
|
12
|
+
}
|
|
13
|
+
/**
|
|
14
|
+
* Pages create some ids in the browser (a new record, a draft, a field) and later check that an answer names the same
|
|
15
|
+
* id. During playback the page draws fresh ids, so a recorded answer would name an id the page never made.
|
|
16
|
+
* An id is aliased only when the live value appears nowhere in the recording: such a value can only have been generated
|
|
17
|
+
* by the page itself, never read from a recorded answer.
|
|
18
|
+
*/ export function createIdAliases(recordedTexts) {
|
|
19
|
+
const known = new Set(idsIn(recordedTexts));
|
|
20
|
+
const toLive = new Map();
|
|
21
|
+
const toRecorded = new Map();
|
|
22
|
+
const pair = (live, recorded)=>{
|
|
23
|
+
if (live === recorded || known.has(live) || !known.has(recorded) || toLive.has(recorded) || toRecorded.has(live)) return;
|
|
24
|
+
toLive.set(recorded, live);
|
|
25
|
+
toRecorded.set(live, recorded);
|
|
26
|
+
};
|
|
27
|
+
const walk = (live, recorded)=>{
|
|
28
|
+
if (typeof live === 'string' && typeof recorded === 'string') {
|
|
29
|
+
if (wholeUuid.test(live) && wholeUuid.test(recorded)) pair(live, recorded);
|
|
30
|
+
return;
|
|
31
|
+
}
|
|
32
|
+
if (Array.isArray(live) && Array.isArray(recorded)) {
|
|
33
|
+
live.forEach((item, index)=>{
|
|
34
|
+
const other = recorded[index];
|
|
35
|
+
if (other !== undefined) walk(item, other);
|
|
36
|
+
});
|
|
37
|
+
return;
|
|
38
|
+
}
|
|
39
|
+
if (live === null || recorded === null || typeof live !== 'object' || typeof recorded !== 'object' || Array.isArray(live) || Array.isArray(recorded)) return;
|
|
40
|
+
for (const [key, item] of Object.entries(live)){
|
|
41
|
+
const other = recorded[key];
|
|
42
|
+
if (other !== undefined) walk(item, other);
|
|
43
|
+
}
|
|
44
|
+
};
|
|
45
|
+
return {
|
|
46
|
+
learn: (live, recorded)=>walk(live, recorded),
|
|
47
|
+
know: (texts)=>{
|
|
48
|
+
for (const id of idsIn(texts))known.add(id);
|
|
49
|
+
},
|
|
50
|
+
toRecorded: (text)=>replaceIds(text, toRecorded),
|
|
51
|
+
toLive: (text)=>replaceIds(text, toLive)
|
|
52
|
+
};
|
|
53
|
+
}
|
|
54
|
+
/** Learns from two payload texts; either may be absent (a call without a payload teaches nothing). */ export function learnFromTexts(aliases, live, recorded) {
|
|
55
|
+
if (live === null || recorded === null) return;
|
|
56
|
+
aliases.learn(parse(live), parse(recorded));
|
|
57
|
+
}
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import type { ApiResponse } from '../../ApiCaller/types';
|
|
2
|
+
import type { AssetRef, JsonValue, Ms, RecordedAnswer } from '../contract/types';
|
|
3
|
+
import { DEFAULT_READ_KEYS } from './match';
|
|
4
|
+
export { DEFAULT_READ_KEYS };
|
|
5
|
+
export interface ReplayFactoryOptions {
|
|
6
|
+
/** The recorded clock now, in ms from the start of the recording. */
|
|
7
|
+
playhead: () => Ms;
|
|
8
|
+
/** Called once per endpoint key the first time no recorded answer covers a call. */
|
|
9
|
+
onUnanswered?: (key: string) => void;
|
|
10
|
+
/** Turns an `AssetRef` found in a body into the string the UI expects (usually a data URL or a path). */
|
|
11
|
+
resolveAsset?: (ref: AssetRef) => string;
|
|
12
|
+
/** Keys that only read; `GET_` keys always do. Defaults to `DEFAULT_READ_KEYS`. */
|
|
13
|
+
readKeys?: Iterable<string>;
|
|
14
|
+
}
|
|
15
|
+
/** A typed API factory that never touches the network; `add` feeds it the answers of a chapter loaded later. */
|
|
16
|
+
export type ReplayFactory<P = JsonValue | undefined, S = JsonValue, E = JsonValue> = ((key: string, payload: P) => Promise<ApiResponse<S, E>>) & {
|
|
17
|
+
add: (answers: readonly RecordedAnswer[]) => void;
|
|
18
|
+
};
|
|
19
|
+
/**
|
|
20
|
+
* A factory with the signature of an app's typed API factory that never touches the network. Answers recorded
|
|
21
|
+
* with `at` are due once the playhead reaches them; answers without it are served by order and write epochs, exactly
|
|
22
|
+
* as schema version 1 recordings were. Ids the page generated itself are carried through: see `createIdAliases`.
|
|
23
|
+
*/
|
|
24
|
+
export declare function createReplayFactory<P = JsonValue | undefined, S = JsonValue, E = JsonValue>(source: readonly RecordedAnswer[], options: ReplayFactoryOptions): ReplayFactory<P, S, E>;
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
import { REPLAY_UNANSWERED } from '../contract/types';
|
|
2
|
+
import { createIdAliases, learnFromTexts } from './aliases';
|
|
3
|
+
import { DEFAULT_READ_KEYS, nextEntry } from './match';
|
|
4
|
+
export { DEFAULT_READ_KEYS };
|
|
5
|
+
const assetPattern = /asset:[A-Za-z0-9._-]+/g;
|
|
6
|
+
function isAssetRef(text) {
|
|
7
|
+
return text.startsWith('asset:');
|
|
8
|
+
}
|
|
9
|
+
/** Parsing is the same untyped boundary the network client uses; it also hands every caller a private copy. */ function revive(text) {
|
|
10
|
+
return JSON.parse(text);
|
|
11
|
+
}
|
|
12
|
+
function payloadText(payload) {
|
|
13
|
+
return payload === undefined || payload === null ? null : JSON.stringify(payload);
|
|
14
|
+
}
|
|
15
|
+
function withAssets(raw, resolve) {
|
|
16
|
+
if (!resolve) return raw;
|
|
17
|
+
return raw.replace(assetPattern, (match)=>isAssetRef(match) ? JSON.stringify(resolve(match)).slice(1, -1) : match);
|
|
18
|
+
}
|
|
19
|
+
/**
|
|
20
|
+
* A factory with the signature of an app's typed API factory that never touches the network. Answers recorded
|
|
21
|
+
* with `at` are due once the playhead reaches them; answers without it are served by order and write epochs, exactly
|
|
22
|
+
* as schema version 1 recordings were. Ids the page generated itself are carried through: see `createIdAliases`.
|
|
23
|
+
*/ export function createReplayFactory(source, options) {
|
|
24
|
+
const reads = new Set(options.readKeys ?? DEFAULT_READ_KEYS);
|
|
25
|
+
const isWrite = (key)=>!key.startsWith('GET_') && !reads.has(key);
|
|
26
|
+
const queues = new Map();
|
|
27
|
+
const reported = new Set();
|
|
28
|
+
const aliases = createIdAliases([]);
|
|
29
|
+
let writes = 0;
|
|
30
|
+
let epoch = 0;
|
|
31
|
+
const add = (answers)=>{
|
|
32
|
+
const texts = [];
|
|
33
|
+
for (const answer of answers){
|
|
34
|
+
const queue = queues.get(answer.key) ?? {
|
|
35
|
+
entries: [],
|
|
36
|
+
last: null
|
|
37
|
+
};
|
|
38
|
+
const write = isWrite(answer.key);
|
|
39
|
+
const entry = {
|
|
40
|
+
status: answer.status,
|
|
41
|
+
raw: JSON.stringify(answer.body),
|
|
42
|
+
payload: payloadText(answer.payload),
|
|
43
|
+
at: answer.at,
|
|
44
|
+
served: false,
|
|
45
|
+
epoch: writes,
|
|
46
|
+
write
|
|
47
|
+
};
|
|
48
|
+
queue.entries.push(entry);
|
|
49
|
+
if (write && answer.at === undefined) writes += 1;
|
|
50
|
+
queues.set(answer.key, queue);
|
|
51
|
+
texts.push(entry.raw, entry.payload ?? '');
|
|
52
|
+
}
|
|
53
|
+
aliases.know(texts);
|
|
54
|
+
};
|
|
55
|
+
add(source);
|
|
56
|
+
const unanswered = (key)=>{
|
|
57
|
+
if (!reported.has(key)) {
|
|
58
|
+
reported.add(key);
|
|
59
|
+
options.onUnanswered?.(key);
|
|
60
|
+
}
|
|
61
|
+
const message = `no recorded answer for ${key}`;
|
|
62
|
+
return {
|
|
63
|
+
isSuccess: false,
|
|
64
|
+
code: 503,
|
|
65
|
+
errors: revive(JSON.stringify({
|
|
66
|
+
code: REPLAY_UNANSWERED,
|
|
67
|
+
message
|
|
68
|
+
}))
|
|
69
|
+
};
|
|
70
|
+
};
|
|
71
|
+
const call = async (key, payload)=>{
|
|
72
|
+
const queue = queues.get(key);
|
|
73
|
+
const live = payload === undefined || payload === null ? null : JSON.stringify(payload);
|
|
74
|
+
const entry = queue ? nextEntry(queue, live === null ? null : aliases.toRecorded(live), {
|
|
75
|
+
epoch,
|
|
76
|
+
playhead: options.playhead()
|
|
77
|
+
}) : undefined;
|
|
78
|
+
if (!queue || !entry) return unanswered(key);
|
|
79
|
+
learnFromTexts(aliases, live, entry.payload);
|
|
80
|
+
if (entry.write && !entry.served && entry.at === undefined) epoch = Math.max(epoch, entry.epoch + 1);
|
|
81
|
+
entry.served = true;
|
|
82
|
+
queue.last = entry;
|
|
83
|
+
const body = withAssets(aliases.toLive(entry.raw), options.resolveAsset);
|
|
84
|
+
return entry.status >= 200 && entry.status < 300 ? {
|
|
85
|
+
isSuccess: true,
|
|
86
|
+
code: entry.status,
|
|
87
|
+
data: revive(body)
|
|
88
|
+
} : {
|
|
89
|
+
isSuccess: false,
|
|
90
|
+
code: entry.status,
|
|
91
|
+
errors: revive(body)
|
|
92
|
+
};
|
|
93
|
+
};
|
|
94
|
+
return Object.assign(call, {
|
|
95
|
+
add
|
|
96
|
+
});
|
|
97
|
+
}
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
import type { Ms } from '../contract/types';
|
|
2
|
+
/**
|
|
3
|
+
* `epoch`: how many writes the recording had made when this answer was recorded (see `isWrite`). Answers without `at`
|
|
4
|
+
* are gated by it; answers with `at` are gated by the playhead.
|
|
5
|
+
*/
|
|
6
|
+
export type Entry = {
|
|
7
|
+
status: number;
|
|
8
|
+
raw: string;
|
|
9
|
+
payload: string | null;
|
|
10
|
+
at: Ms | undefined;
|
|
11
|
+
served: boolean;
|
|
12
|
+
epoch: number;
|
|
13
|
+
write: boolean;
|
|
14
|
+
};
|
|
15
|
+
export type Queue = {
|
|
16
|
+
entries: Entry[];
|
|
17
|
+
last: Entry | null;
|
|
18
|
+
};
|
|
19
|
+
/** What decides which answers are due right now. */
|
|
20
|
+
export type Clock = {
|
|
21
|
+
epoch: number;
|
|
22
|
+
playhead: Ms;
|
|
23
|
+
};
|
|
24
|
+
/** Endpoints that only read, besides every `GET_` key. Any other key is a write the visitor's actions trigger. */
|
|
25
|
+
export declare const DEFAULT_READ_KEYS: readonly string[];
|
|
26
|
+
/**
|
|
27
|
+
* The answer for one call: among the answers due now, the one recorded for the same payload (a search, a filter, a
|
|
28
|
+
* page), otherwise the latest of the key; otherwise the latest answer already in the past for that payload, the one
|
|
29
|
+
* served last, the latest in the past, and finally the first answer recorded without a time. A replayed page does not
|
|
30
|
+
* always repeat the recorded number of calls (a remount, a debounce); matching the payload keeps such a drift from
|
|
31
|
+
* handing one screen the answer that belonged to another. An answer recorded after a write is served only once the
|
|
32
|
+
* replay has made that write; one recorded with a time only once the playhead has reached it.
|
|
33
|
+
*/
|
|
34
|
+
export declare function nextEntry(queue: Queue, payload: string | null, clock: Clock): Entry | undefined;
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
/** Endpoints that only read, besides every `GET_` key. Any other key is a write the visitor's actions trigger. */ export const DEFAULT_READ_KEYS = [
|
|
2
|
+
'ME',
|
|
3
|
+
'NOTIFICATION_UNSEEN_COUNT'
|
|
4
|
+
];
|
|
5
|
+
function due(entry, clock, floor) {
|
|
6
|
+
if (entry.at !== undefined) return entry.at <= clock.playhead && !(entry.write && entry.served);
|
|
7
|
+
return !entry.served && entry.epoch <= clock.epoch && entry.epoch >= floor;
|
|
8
|
+
}
|
|
9
|
+
/** The nearest answer to the present: the latest `at`, otherwise the earliest of the highest epoch. */ function latest(entries) {
|
|
10
|
+
const timed = entries.filter((entry)=>entry.at !== undefined);
|
|
11
|
+
if (timed.length > 0) return timed.reduce((best, entry)=>(entry.at ?? 0) >= (best.at ?? 0) ? entry : best);
|
|
12
|
+
return entries.reduce((best, entry)=>!best || entry.epoch > best.epoch ? entry : best, undefined);
|
|
13
|
+
}
|
|
14
|
+
function seen(entry, clock) {
|
|
15
|
+
return entry.at !== undefined ? entry.at <= clock.playhead : entry.epoch <= clock.epoch;
|
|
16
|
+
}
|
|
17
|
+
/**
|
|
18
|
+
* The answer for one call: among the answers due now, the one recorded for the same payload (a search, a filter, a
|
|
19
|
+
* page), otherwise the latest of the key; otherwise the latest answer already in the past for that payload, the one
|
|
20
|
+
* served last, the latest in the past, and finally the first answer recorded without a time. A replayed page does not
|
|
21
|
+
* always repeat the recorded number of calls (a remount, a debounce); matching the payload keeps such a drift from
|
|
22
|
+
* handing one screen the answer that belonged to another. An answer recorded after a write is served only once the
|
|
23
|
+
* replay has made that write; one recorded with a time only once the playhead has reached it.
|
|
24
|
+
*/ export function nextEntry(queue, payload, clock) {
|
|
25
|
+
const floor = queue.last?.at === undefined ? queue.last?.epoch ?? 0 : 0;
|
|
26
|
+
const ready = queue.entries.filter((entry)=>due(entry, clock, floor));
|
|
27
|
+
const fresh = latest(ready.filter((entry)=>entry.payload === payload)) ?? latest(ready);
|
|
28
|
+
if (fresh) return fresh;
|
|
29
|
+
const past = queue.entries.filter((entry)=>seen(entry, clock));
|
|
30
|
+
return [
|
|
31
|
+
...past
|
|
32
|
+
].reverse().find((entry)=>entry.payload === payload) ?? queue.last ?? past.at(-1) ?? queue.entries.find((entry)=>entry.at === undefined);
|
|
33
|
+
}
|
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
import { type Static } from '@sinclair/typebox';
|
|
2
|
+
import type { JsonValue } from '../contract/types';
|
|
3
|
+
/**
|
|
4
|
+
* The parent page <-> replay frame protocol. Both sides are the same origin; every message carries the
|
|
5
|
+
* envelope (channel name, version, the nonce of the frame session) and is validated structurally before use.
|
|
6
|
+
*/
|
|
7
|
+
export declare const REPLAY_CHANNEL = "nucleus.replay";
|
|
8
|
+
export declare const REPLAY_CHANNEL_VERSION = 1;
|
|
9
|
+
/** Why an action failed; the driver reports it, the player shows or logs it. */
|
|
10
|
+
export declare const FailureReasonSchema: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"target_timeout">, import("@sinclair/typebox").TLiteral<"target_unsupported">, import("@sinclair/typebox").TLiteral<"option_not_found">, import("@sinclair/typebox").TLiteral<"navigate_failed">, import("@sinclair/typebox").TLiteral<"action_error">, import("@sinclair/typebox").TLiteral<"step_unknown">]>;
|
|
11
|
+
export type FailureReason = Static<typeof FailureReasonSchema>;
|
|
12
|
+
/** A target's box in frame viewport pixels, with the viewport it was measured in so the cursor can scale it. */
|
|
13
|
+
export declare const PointBoxSchema: import("@sinclair/typebox").TObject<{
|
|
14
|
+
x: import("@sinclair/typebox").TNumber;
|
|
15
|
+
y: import("@sinclair/typebox").TNumber;
|
|
16
|
+
width: import("@sinclair/typebox").TNumber;
|
|
17
|
+
height: import("@sinclair/typebox").TNumber;
|
|
18
|
+
viewportWidth: import("@sinclair/typebox").TNumber;
|
|
19
|
+
viewportHeight: import("@sinclair/typebox").TNumber;
|
|
20
|
+
}>;
|
|
21
|
+
export type PointBox = Static<typeof PointBoxSchema>;
|
|
22
|
+
/** What the embedding page sends to the frame. */
|
|
23
|
+
export declare const ParentMessageSchema: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TObject<{
|
|
24
|
+
type: import("@sinclair/typebox").TLiteral<"hello">;
|
|
25
|
+
channel: import("@sinclair/typebox").TLiteral<"nucleus.replay">;
|
|
26
|
+
version: import("@sinclair/typebox").TLiteral<1>;
|
|
27
|
+
nonce: import("@sinclair/typebox").TString;
|
|
28
|
+
}>, import("@sinclair/typebox").TObject<{
|
|
29
|
+
type: import("@sinclair/typebox").TLiteral<"play">;
|
|
30
|
+
channel: import("@sinclair/typebox").TLiteral<"nucleus.replay">;
|
|
31
|
+
version: import("@sinclair/typebox").TLiteral<1>;
|
|
32
|
+
nonce: import("@sinclair/typebox").TString;
|
|
33
|
+
}>, import("@sinclair/typebox").TObject<{
|
|
34
|
+
type: import("@sinclair/typebox").TLiteral<"pause">;
|
|
35
|
+
channel: import("@sinclair/typebox").TLiteral<"nucleus.replay">;
|
|
36
|
+
version: import("@sinclair/typebox").TLiteral<1>;
|
|
37
|
+
nonce: import("@sinclair/typebox").TString;
|
|
38
|
+
}>, import("@sinclair/typebox").TObject<{
|
|
39
|
+
type: import("@sinclair/typebox").TLiteral<"seek">;
|
|
40
|
+
at: import("@sinclair/typebox").TNumber;
|
|
41
|
+
channel: import("@sinclair/typebox").TLiteral<"nucleus.replay">;
|
|
42
|
+
version: import("@sinclair/typebox").TLiteral<1>;
|
|
43
|
+
nonce: import("@sinclair/typebox").TString;
|
|
44
|
+
}>, import("@sinclair/typebox").TObject<{
|
|
45
|
+
type: import("@sinclair/typebox").TLiteral<"rate">;
|
|
46
|
+
rate: import("@sinclair/typebox").TNumber;
|
|
47
|
+
channel: import("@sinclair/typebox").TLiteral<"nucleus.replay">;
|
|
48
|
+
version: import("@sinclair/typebox").TLiteral<1>;
|
|
49
|
+
nonce: import("@sinclair/typebox").TString;
|
|
50
|
+
}>, import("@sinclair/typebox").TObject<{
|
|
51
|
+
type: import("@sinclair/typebox").TLiteral<"cursor-arrived">;
|
|
52
|
+
mark: import("@sinclair/typebox").TInteger;
|
|
53
|
+
channel: import("@sinclair/typebox").TLiteral<"nucleus.replay">;
|
|
54
|
+
version: import("@sinclair/typebox").TLiteral<1>;
|
|
55
|
+
nonce: import("@sinclair/typebox").TString;
|
|
56
|
+
}>]>;
|
|
57
|
+
export type ParentMessage = Static<typeof ParentMessageSchema>;
|
|
58
|
+
/** What the frame sends to the embedding page. */
|
|
59
|
+
export declare const FrameMessageSchema: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TObject<{
|
|
60
|
+
type: import("@sinclair/typebox").TLiteral<"ready">;
|
|
61
|
+
recordingId: import("@sinclair/typebox").TString;
|
|
62
|
+
channel: import("@sinclair/typebox").TLiteral<"nucleus.replay">;
|
|
63
|
+
version: import("@sinclair/typebox").TLiteral<1>;
|
|
64
|
+
nonce: import("@sinclair/typebox").TString;
|
|
65
|
+
}>, import("@sinclair/typebox").TObject<{
|
|
66
|
+
type: import("@sinclair/typebox").TLiteral<"step-started">;
|
|
67
|
+
stepId: import("@sinclair/typebox").TString;
|
|
68
|
+
channel: import("@sinclair/typebox").TLiteral<"nucleus.replay">;
|
|
69
|
+
version: import("@sinclair/typebox").TLiteral<1>;
|
|
70
|
+
nonce: import("@sinclair/typebox").TString;
|
|
71
|
+
}>, import("@sinclair/typebox").TObject<{
|
|
72
|
+
type: import("@sinclair/typebox").TLiteral<"point">;
|
|
73
|
+
stepId: import("@sinclair/typebox").TString;
|
|
74
|
+
mark: import("@sinclair/typebox").TInteger;
|
|
75
|
+
box: import("@sinclair/typebox").TObject<{
|
|
76
|
+
x: import("@sinclair/typebox").TNumber;
|
|
77
|
+
y: import("@sinclair/typebox").TNumber;
|
|
78
|
+
width: import("@sinclair/typebox").TNumber;
|
|
79
|
+
height: import("@sinclair/typebox").TNumber;
|
|
80
|
+
viewportWidth: import("@sinclair/typebox").TNumber;
|
|
81
|
+
viewportHeight: import("@sinclair/typebox").TNumber;
|
|
82
|
+
}>;
|
|
83
|
+
channel: import("@sinclair/typebox").TLiteral<"nucleus.replay">;
|
|
84
|
+
version: import("@sinclair/typebox").TLiteral<1>;
|
|
85
|
+
nonce: import("@sinclair/typebox").TString;
|
|
86
|
+
}>, import("@sinclair/typebox").TObject<{
|
|
87
|
+
type: import("@sinclair/typebox").TLiteral<"step-done">;
|
|
88
|
+
stepId: import("@sinclair/typebox").TString;
|
|
89
|
+
channel: import("@sinclair/typebox").TLiteral<"nucleus.replay">;
|
|
90
|
+
version: import("@sinclair/typebox").TLiteral<1>;
|
|
91
|
+
nonce: import("@sinclair/typebox").TString;
|
|
92
|
+
}>, import("@sinclair/typebox").TObject<{
|
|
93
|
+
type: import("@sinclair/typebox").TLiteral<"step-failed">;
|
|
94
|
+
stepId: import("@sinclair/typebox").TString;
|
|
95
|
+
actionIndex: import("@sinclair/typebox").TInteger;
|
|
96
|
+
reason: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"target_timeout">, import("@sinclair/typebox").TLiteral<"target_unsupported">, import("@sinclair/typebox").TLiteral<"option_not_found">, import("@sinclair/typebox").TLiteral<"navigate_failed">, import("@sinclair/typebox").TLiteral<"action_error">, import("@sinclair/typebox").TLiteral<"step_unknown">]>;
|
|
97
|
+
channel: import("@sinclair/typebox").TLiteral<"nucleus.replay">;
|
|
98
|
+
version: import("@sinclair/typebox").TLiteral<1>;
|
|
99
|
+
nonce: import("@sinclair/typebox").TString;
|
|
100
|
+
}>, import("@sinclair/typebox").TObject<{
|
|
101
|
+
type: import("@sinclair/typebox").TLiteral<"tick">;
|
|
102
|
+
at: import("@sinclair/typebox").TNumber;
|
|
103
|
+
playing: import("@sinclair/typebox").TBoolean;
|
|
104
|
+
channel: import("@sinclair/typebox").TLiteral<"nucleus.replay">;
|
|
105
|
+
version: import("@sinclair/typebox").TLiteral<1>;
|
|
106
|
+
nonce: import("@sinclair/typebox").TString;
|
|
107
|
+
}>, import("@sinclair/typebox").TObject<{
|
|
108
|
+
type: import("@sinclair/typebox").TLiteral<"unanswered">;
|
|
109
|
+
key: import("@sinclair/typebox").TString;
|
|
110
|
+
channel: import("@sinclair/typebox").TLiteral<"nucleus.replay">;
|
|
111
|
+
version: import("@sinclair/typebox").TLiteral<1>;
|
|
112
|
+
nonce: import("@sinclair/typebox").TString;
|
|
113
|
+
}>]>;
|
|
114
|
+
export type FrameMessage = Static<typeof FrameMessageSchema>;
|
|
115
|
+
/** What a `message` event carries; a real `MessageEvent` satisfies it. */
|
|
116
|
+
export interface ChannelEvent {
|
|
117
|
+
origin: string;
|
|
118
|
+
source: object | null;
|
|
119
|
+
data: JsonValue;
|
|
120
|
+
}
|
|
121
|
+
/** The side that reads: its own origin, the window it expects messages from, and the session nonce. */
|
|
122
|
+
export interface ChannelPeer {
|
|
123
|
+
origin: string;
|
|
124
|
+
peer: object | null;
|
|
125
|
+
nonce: string;
|
|
126
|
+
}
|
|
127
|
+
/** A fresh session nonce: 128 random bits as hex. The parent mints it and hands it to the frame in the URL. */
|
|
128
|
+
export declare function createNonce(): string;
|
|
129
|
+
/** A message from the embedding page, or null: wrong origin, wrong window, wrong nonce or wrong shape. */
|
|
130
|
+
export declare function readParentMessage(event: ChannelEvent, own: ChannelPeer): ParentMessage | null;
|
|
131
|
+
/** A message from the frame, or null: wrong origin, wrong window, wrong nonce or wrong shape. */
|
|
132
|
+
export declare function readFrameMessage(event: ChannelEvent, own: ChannelPeer): FrameMessage | null;
|
|
133
|
+
/** Anything with `postMessage(message, targetOrigin)`: a `Window`. */
|
|
134
|
+
export interface MessageTarget {
|
|
135
|
+
postMessage: (message: ParentMessage | FrameMessage, targetOrigin: string) => void;
|
|
136
|
+
}
|
|
137
|
+
/** Posts to the other side, addressed to this origin only so no other origin can read it. */
|
|
138
|
+
export declare function sendMessage(target: MessageTarget, origin: string, message: ParentMessage | FrameMessage): void;
|
|
139
|
+
/** The envelope fields for a session, to spread into every message: `{ ...envelopeFor(nonce), type: 'play' }`. */
|
|
140
|
+
export declare function envelopeFor(sessionNonce: string): {
|
|
141
|
+
channel: typeof REPLAY_CHANNEL;
|
|
142
|
+
version: typeof REPLAY_CHANNEL_VERSION;
|
|
143
|
+
nonce: string;
|
|
144
|
+
};
|
|
@@ -0,0 +1,150 @@
|
|
|
1
|
+
import { Type } from '@sinclair/typebox';
|
|
2
|
+
import { Value } from '@sinclair/typebox/value';
|
|
3
|
+
/**
|
|
4
|
+
* The parent page <-> replay frame protocol. Both sides are the same origin; every message carries the
|
|
5
|
+
* envelope (channel name, version, the nonce of the frame session) and is validated structurally before use.
|
|
6
|
+
*/ export const REPLAY_CHANNEL = 'nucleus.replay';
|
|
7
|
+
export const REPLAY_CHANNEL_VERSION = 1;
|
|
8
|
+
/** Why an action failed; the driver reports it, the player shows or logs it. */ export const FailureReasonSchema = Type.Union([
|
|
9
|
+
Type.Literal('target_timeout'),
|
|
10
|
+
Type.Literal('target_unsupported'),
|
|
11
|
+
Type.Literal('option_not_found'),
|
|
12
|
+
Type.Literal('navigate_failed'),
|
|
13
|
+
Type.Literal('action_error'),
|
|
14
|
+
Type.Literal('step_unknown')
|
|
15
|
+
]);
|
|
16
|
+
/** A target's box in frame viewport pixels, with the viewport it was measured in so the cursor can scale it. */ export const PointBoxSchema = Type.Object({
|
|
17
|
+
x: Type.Number(),
|
|
18
|
+
y: Type.Number(),
|
|
19
|
+
width: Type.Number(),
|
|
20
|
+
height: Type.Number(),
|
|
21
|
+
viewportWidth: Type.Number(),
|
|
22
|
+
viewportHeight: Type.Number()
|
|
23
|
+
}, {
|
|
24
|
+
additionalProperties: false
|
|
25
|
+
});
|
|
26
|
+
const nonce = Type.String({
|
|
27
|
+
minLength: 16,
|
|
28
|
+
maxLength: 128,
|
|
29
|
+
pattern: '^[0-9a-f]+$'
|
|
30
|
+
});
|
|
31
|
+
const envelope = {
|
|
32
|
+
channel: Type.Literal(REPLAY_CHANNEL),
|
|
33
|
+
version: Type.Literal(REPLAY_CHANNEL_VERSION),
|
|
34
|
+
nonce
|
|
35
|
+
};
|
|
36
|
+
const id = Type.String({
|
|
37
|
+
minLength: 1,
|
|
38
|
+
maxLength: 200
|
|
39
|
+
});
|
|
40
|
+
const ms = Type.Number({
|
|
41
|
+
minimum: 0
|
|
42
|
+
});
|
|
43
|
+
const strict = {
|
|
44
|
+
additionalProperties: false
|
|
45
|
+
};
|
|
46
|
+
/** What the embedding page sends to the frame. */ export const ParentMessageSchema = Type.Union([
|
|
47
|
+
/** Asks the frame to announce `ready` again: its first announcement may reach no listener yet. */ Type.Object({
|
|
48
|
+
...envelope,
|
|
49
|
+
type: Type.Literal('hello')
|
|
50
|
+
}, strict),
|
|
51
|
+
Type.Object({
|
|
52
|
+
...envelope,
|
|
53
|
+
type: Type.Literal('play')
|
|
54
|
+
}, strict),
|
|
55
|
+
Type.Object({
|
|
56
|
+
...envelope,
|
|
57
|
+
type: Type.Literal('pause')
|
|
58
|
+
}, strict),
|
|
59
|
+
/** Chapters are the only seek points; `at` is a recorded-clock offset the frame snaps to. */ Type.Object({
|
|
60
|
+
...envelope,
|
|
61
|
+
type: Type.Literal('seek'),
|
|
62
|
+
at: ms
|
|
63
|
+
}, strict),
|
|
64
|
+
Type.Object({
|
|
65
|
+
...envelope,
|
|
66
|
+
type: Type.Literal('rate'),
|
|
67
|
+
rate: Type.Number({
|
|
68
|
+
exclusiveMinimum: 0,
|
|
69
|
+
maximum: 64
|
|
70
|
+
})
|
|
71
|
+
}, strict),
|
|
72
|
+
/** The drawn cursor reached the box the frame reported as `mark`; the driver may act now. */ Type.Object({
|
|
73
|
+
...envelope,
|
|
74
|
+
type: Type.Literal('cursor-arrived'),
|
|
75
|
+
mark: Type.Integer({
|
|
76
|
+
minimum: 0
|
|
77
|
+
})
|
|
78
|
+
}, strict)
|
|
79
|
+
]);
|
|
80
|
+
/** What the frame sends to the embedding page. */ export const FrameMessageSchema = Type.Union([
|
|
81
|
+
Type.Object({
|
|
82
|
+
...envelope,
|
|
83
|
+
type: Type.Literal('ready'),
|
|
84
|
+
recordingId: id
|
|
85
|
+
}, strict),
|
|
86
|
+
Type.Object({
|
|
87
|
+
...envelope,
|
|
88
|
+
type: Type.Literal('step-started'),
|
|
89
|
+
stepId: id
|
|
90
|
+
}, strict),
|
|
91
|
+
Type.Object({
|
|
92
|
+
...envelope,
|
|
93
|
+
type: Type.Literal('point'),
|
|
94
|
+
stepId: id,
|
|
95
|
+
mark: Type.Integer({
|
|
96
|
+
minimum: 0
|
|
97
|
+
}),
|
|
98
|
+
box: PointBoxSchema
|
|
99
|
+
}, strict),
|
|
100
|
+
Type.Object({
|
|
101
|
+
...envelope,
|
|
102
|
+
type: Type.Literal('step-done'),
|
|
103
|
+
stepId: id
|
|
104
|
+
}, strict),
|
|
105
|
+
Type.Object({
|
|
106
|
+
...envelope,
|
|
107
|
+
type: Type.Literal('step-failed'),
|
|
108
|
+
stepId: id,
|
|
109
|
+
actionIndex: Type.Integer({
|
|
110
|
+
minimum: 0
|
|
111
|
+
}),
|
|
112
|
+
reason: FailureReasonSchema
|
|
113
|
+
}, strict),
|
|
114
|
+
/** The playhead, on the recorded clock; sent a few times a second while playing. */ Type.Object({
|
|
115
|
+
...envelope,
|
|
116
|
+
type: Type.Literal('tick'),
|
|
117
|
+
at: ms,
|
|
118
|
+
playing: Type.Boolean()
|
|
119
|
+
}, strict),
|
|
120
|
+
/** A call no recorded answer covered (`replay_unanswered`): the audit fails on any. */ Type.Object({
|
|
121
|
+
...envelope,
|
|
122
|
+
type: Type.Literal('unanswered'),
|
|
123
|
+
key: id
|
|
124
|
+
}, strict)
|
|
125
|
+
]);
|
|
126
|
+
/** A fresh session nonce: 128 random bits as hex. The parent mints it and hands it to the frame in the URL. */ export function createNonce() {
|
|
127
|
+
const bytes = crypto.getRandomValues(new Uint8Array(16));
|
|
128
|
+
return Array.from(bytes, (byte)=>byte.toString(16).padStart(2, '0')).join('');
|
|
129
|
+
}
|
|
130
|
+
function trusted(event, own) {
|
|
131
|
+
return event.origin === own.origin && event.source !== null && event.source === own.peer;
|
|
132
|
+
}
|
|
133
|
+
/** A message from the embedding page, or null: wrong origin, wrong window, wrong nonce or wrong shape. */ export function readParentMessage(event, own) {
|
|
134
|
+
if (!trusted(event, own) || !Value.Check(ParentMessageSchema, event.data)) return null;
|
|
135
|
+
return event.data.nonce === own.nonce ? event.data : null;
|
|
136
|
+
}
|
|
137
|
+
/** A message from the frame, or null: wrong origin, wrong window, wrong nonce or wrong shape. */ export function readFrameMessage(event, own) {
|
|
138
|
+
if (!trusted(event, own) || !Value.Check(FrameMessageSchema, event.data)) return null;
|
|
139
|
+
return event.data.nonce === own.nonce ? event.data : null;
|
|
140
|
+
}
|
|
141
|
+
/** Posts to the other side, addressed to this origin only so no other origin can read it. */ export function sendMessage(target, origin, message) {
|
|
142
|
+
target.postMessage(message, origin);
|
|
143
|
+
}
|
|
144
|
+
/** The envelope fields for a session, to spread into every message: `{ ...envelopeFor(nonce), type: 'play' }`. */ export function envelopeFor(sessionNonce) {
|
|
145
|
+
return {
|
|
146
|
+
channel: REPLAY_CHANNEL,
|
|
147
|
+
version: REPLAY_CHANNEL_VERSION,
|
|
148
|
+
nonce: sessionNonce
|
|
149
|
+
};
|
|
150
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export * from './channel';
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export * from './channel';
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
import type { ChapterChunk, ReplayManifest } from './types';
|
|
2
|
+
export type ParseResult<T> = {
|
|
3
|
+
ok: true;
|
|
4
|
+
value: T;
|
|
5
|
+
} | {
|
|
6
|
+
ok: false;
|
|
7
|
+
errors: string[];
|
|
8
|
+
};
|
|
9
|
+
/** Reads a recording manifest (schema version 2, or a version 1 recording lifted to it). Never throws on bad input. */
|
|
10
|
+
export declare function parseManifest(text: string): ParseResult<ReplayManifest>;
|
|
11
|
+
/** Reads one chapter chunk. Never throws on bad input. */
|
|
12
|
+
export declare function parseChapterChunk(text: string): ParseResult<ChapterChunk>;
|