@velmlabs/unstuck-protocol 0.2.0 → 0.2.1

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/index.d.ts CHANGED
@@ -1,14 +1,26 @@
1
1
  import * as _sinclair_typebox from '@sinclair/typebox';
2
2
  import { Static } from '@sinclair/typebox';
3
3
 
4
- /** Binary viewer frame: [type u8][width u16 BE][height u16 BE][JPEG bytes]. Width/height are page CSS pixels. */
4
+ /**
5
+ * Binary viewer frames. Width/height are page CSS pixels.
6
+ * - type 1: [0x01][width u16 BE][height u16 BE][JPEG bytes]
7
+ * - type 2: [0x02][seq u32 BE][width u16 BE][height u16 BE][JPEG bytes] — only sent to a viewer that opted in to frame
8
+ * credit (`{ t: 'credit', v: 1 }`), which acks each drawn frame by its sequence number.
9
+ */
5
10
  declare const FRAME_TYPE_JPEG = 1;
11
+ declare const FRAME_TYPE_JPEG_SEQ = 2;
12
+ declare const FRAME_SEQ_MAX = 4294967295;
6
13
  interface Frame {
7
14
  width: number;
8
15
  height: number;
9
16
  jpeg: Uint8Array;
17
+ /** Set on type-2 frames: the number the viewer acks once it has drawn the frame. */
18
+ seq?: number;
10
19
  }
11
- declare function encodeFrame(f: Frame): Uint8Array;
20
+ /** Encodes a type-1 frame, or a type-2 frame when `seq` is given. */
21
+ declare function encodeFrame(f: Pick<Frame, 'width' | 'height' | 'jpeg'>, seq?: number): Uint8Array;
22
+ /** The same frame as type 2 with this sequence number, from an encoded type-1 frame (the engine caches those). */
23
+ declare function withFrameSeq(type1: Uint8Array, seq: number): Uint8Array;
12
24
  declare function decodeFrame(b: Uint8Array): Frame | null;
13
25
 
14
26
  declare class RpcCallError extends Error {
@@ -168,6 +180,12 @@ declare const ViewerToEngineSchema: _sinclair_typebox.TUnion<[_sinclair_typebox.
168
180
  reason: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
169
181
  }>, _sinclair_typebox.TObject<{
170
182
  t: _sinclair_typebox.TLiteral<"ping">;
183
+ }>, _sinclair_typebox.TObject<{
184
+ t: _sinclair_typebox.TLiteral<"credit">;
185
+ v: _sinclair_typebox.TLiteral<1>;
186
+ }>, _sinclair_typebox.TObject<{
187
+ t: _sinclair_typebox.TLiteral<"ack">;
188
+ seq: _sinclair_typebox.TInteger;
171
189
  }>]>;
172
190
  type ViewerToEngine = Static<typeof ViewerToEngineSchema>;
173
191
  type ViewerInput = Extract<ViewerToEngine, {
@@ -194,6 +212,7 @@ declare const EngineToViewerSchema: _sinclair_typebox.TUnion<[_sinclair_typebox.
194
212
  expiresAt: _sinclair_typebox.TNumber;
195
213
  resumeKey: _sinclair_typebox.TString;
196
214
  vn: _sinclair_typebox.TOptional<_sinclair_typebox.TString>;
215
+ credit: _sinclair_typebox.TOptional<_sinclair_typebox.TLiteral<1>>;
197
216
  }>, _sinclair_typebox.TObject<{
198
217
  t: _sinclair_typebox.TLiteral<"state">;
199
218
  status: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<string>[]>;
@@ -223,13 +242,16 @@ declare const EngineToViewerSchema: _sinclair_typebox.TUnion<[_sinclair_typebox.
223
242
  kind: _sinclair_typebox.TUnion<_sinclair_typebox.TLiteral<"text" | "numeric" | "otp" | "email" | "password">[]>;
224
243
  }>>;
225
244
  }>]>;
226
- type EngineToViewer = {
245
+ type EngineToViewer =
246
+ /** `credit: 1`: this engine paces frames by the viewer's acks once the viewer opts in with `{ t: 'credit', v: 1 }`. */
247
+ {
227
248
  t: 'ready';
228
249
  reason: string;
229
250
  site: string;
230
251
  expiresAt: number;
231
252
  resumeKey: string;
232
253
  vn?: string;
254
+ credit?: 1;
233
255
  } | {
234
256
  t: 'state';
235
257
  status: SessionStatus;
@@ -377,5 +399,5 @@ declare function parseAlertFragment(hash: string): {
377
399
  blob: string;
378
400
  } | null;
379
401
 
380
- export { EngineToViewerSchema, FRAME_TYPE_JPEG, FieldKinds, FieldSchema, KEY_SUBPROTOCOL_PREFIX, Methods, PROTOCOL_VERSION, RELAY_CLOSE, RELAY_LIMITS, RELAY_SUBPROTOCOL, RESUME_WINDOW_MS, RpcCallError, SESSION_ID_RE, SessionStatusSchema, ViewerErrorCodes, ViewerToEngineSchema, b64urlDecode, b64urlEncode, createRpcPeer, decodeEnvelope, decodeFrame, encodeEnvelope, encodeFrame, exportDevicePublicKey, importE2eKey, isJsonPlaintext, newConnNonce, newDeviceKeyPair, newE2eKey, open, openAlert, openMsg, padPlaintext, parseAgentToRelay, parseAlertFragment, parseRelayToAgent, parseViewerMessage, seal, sealAlert, sealMsg };
402
+ export { EngineToViewerSchema, FRAME_SEQ_MAX, FRAME_TYPE_JPEG, FRAME_TYPE_JPEG_SEQ, FieldKinds, FieldSchema, KEY_SUBPROTOCOL_PREFIX, Methods, PROTOCOL_VERSION, RELAY_CLOSE, RELAY_LIMITS, RELAY_SUBPROTOCOL, RESUME_WINDOW_MS, RpcCallError, SESSION_ID_RE, SessionStatusSchema, ViewerErrorCodes, ViewerToEngineSchema, b64urlDecode, b64urlEncode, createRpcPeer, decodeEnvelope, decodeFrame, encodeEnvelope, encodeFrame, exportDevicePublicKey, importE2eKey, isJsonPlaintext, newConnNonce, newDeviceKeyPair, newE2eKey, open, openAlert, openMsg, padPlaintext, parseAgentToRelay, parseAlertFragment, parseRelayToAgent, parseViewerMessage, seal, sealAlert, sealMsg, withFrameSeq };
381
403
  export type { AgentToRelay, AlertPayload, CdpClosedParams, CdpEventParams, CdpSendParams, CdpSubscribeParams, Direction, EngineToViewer, Field, FieldKind, Frame, HelloParams, HelloResult, PagePopupParams, RelayToAgent, RpcError, RpcNotification, RpcPeer, RpcRequest, RpcResponse, SessionStatus, TakeoverLinkParams, TakeoverParams, TakeoverResult, TakeoverStatus, ViewerErrorCode, ViewerInput, ViewerToEngine };
package/dist/index.js CHANGED
@@ -1,10 +1,16 @@
1
1
  // src/frame.ts
2
2
  var FRAME_TYPE_JPEG = 1;
3
+ var FRAME_TYPE_JPEG_SEQ = 2;
4
+ var FRAME_SEQ_MAX = 4294967295;
3
5
  var HEADER = 5;
6
+ var SEQ_BYTES = 4;
4
7
  function checkU16(name, v) {
5
8
  if (!Number.isInteger(v) || v < 0 || v > 65535) throw new RangeError(`${name} must be an integer 0..65535, got ${v}`);
6
9
  }
7
- function encodeFrame(f) {
10
+ function checkSeq(seq) {
11
+ if (!Number.isInteger(seq) || seq < 1 || seq > FRAME_SEQ_MAX) throw new RangeError(`seq must be an integer 1..${FRAME_SEQ_MAX}, got ${seq}`);
12
+ }
13
+ function encodeFrame(f, seq) {
8
14
  checkU16("width", f.width);
9
15
  checkU16("height", f.height);
10
16
  const out = new Uint8Array(HEADER + f.jpeg.length);
@@ -13,12 +19,29 @@ function encodeFrame(f) {
13
19
  view.setUint16(1, f.width);
14
20
  view.setUint16(3, f.height);
15
21
  out.set(f.jpeg, HEADER);
22
+ return seq === void 0 ? out : withFrameSeq(out, seq);
23
+ }
24
+ function withFrameSeq(type1, seq) {
25
+ if (type1.length < HEADER || type1[0] !== FRAME_TYPE_JPEG) throw new RangeError("not a type-1 frame");
26
+ checkSeq(seq);
27
+ const out = new Uint8Array(type1.length + SEQ_BYTES);
28
+ const view = new DataView(out.buffer);
29
+ view.setUint8(0, FRAME_TYPE_JPEG_SEQ);
30
+ view.setUint32(1, seq);
31
+ out.set(type1.subarray(1), 1 + SEQ_BYTES);
16
32
  return out;
17
33
  }
18
34
  function decodeFrame(b) {
19
- if (b.length < HEADER || b[0] !== FRAME_TYPE_JPEG) return null;
20
35
  const view = new DataView(b.buffer, b.byteOffset, b.byteLength);
21
- return { width: view.getUint16(1), height: view.getUint16(3), jpeg: b.slice(HEADER) };
36
+ if (b[0] === FRAME_TYPE_JPEG && b.length >= HEADER) {
37
+ return { width: view.getUint16(1), height: view.getUint16(3), jpeg: b.slice(HEADER) };
38
+ }
39
+ if (b[0] === FRAME_TYPE_JPEG_SEQ && b.length >= HEADER + SEQ_BYTES) {
40
+ const seq = view.getUint32(1);
41
+ if (seq === 0) return null;
42
+ return { width: view.getUint16(5), height: view.getUint16(7), jpeg: b.slice(HEADER + SEQ_BYTES), seq };
43
+ }
44
+ return null;
22
45
  }
23
46
 
24
47
  // src/rpc.ts
@@ -163,14 +186,29 @@ var ViewerToEngineSchema = Type.Union([
163
186
  Type.Object({ t: Lit("text"), text: Type.String() }, { additionalProperties: false }),
164
187
  Type.Object({ t: Lit("done") }, { additionalProperties: false }),
165
188
  Type.Object({ t: Lit("cant_solve"), reason: Type.Optional(Type.String({ maxLength: 200 })) }, { additionalProperties: false }),
166
- Type.Object({ t: Lit("ping") }, { additionalProperties: false })
189
+ Type.Object({ t: Lit("ping") }, { additionalProperties: false }),
190
+ /**
191
+ * Frame credit opt-in, sent only to an engine whose ready says `credit: 1` (older engines refuse unknown messages):
192
+ * from now on the engine sends type-2 frames and keeps at most a few (CREDIT_MAX_IN_FLIGHT in core) unacknowledged.
193
+ */
194
+ Type.Object({ t: Lit("credit"), v: Type.Literal(1) }, { additionalProperties: false }),
195
+ /** This frame (and every earlier one) has been drawn. */
196
+ Type.Object({ t: Lit("ack"), seq: Type.Integer({ minimum: 1, maximum: 4294967295 }) }, { additionalProperties: false })
167
197
  ]);
168
198
  var ViewerErrorCodes = ["token_invalid", "token_used", "expired", "session_closed", "bad_message", "code_required", "code_invalid"];
169
199
  var FieldKinds = ["text", "numeric", "otp", "email", "password"];
170
200
  var FieldKindSchema = Type.Union(FieldKinds.map((k) => Lit(k)));
171
201
  var FieldSchema = Type.Object({ x: Num, y: Num, w: Num, h: Num, kind: FieldKindSchema }, { additionalProperties: false });
172
202
  var EngineToViewerSchema = Type.Union([
173
- Type.Object({ t: Lit("ready"), reason: Type.String(), site: Type.String(), expiresAt: Num, resumeKey: Type.String(), vn: Type.Optional(Type.String()) }),
203
+ Type.Object({
204
+ t: Lit("ready"),
205
+ reason: Type.String(),
206
+ site: Type.String(),
207
+ expiresAt: Num,
208
+ resumeKey: Type.String(),
209
+ vn: Type.Optional(Type.String()),
210
+ credit: Type.Optional(Type.Literal(1))
211
+ }),
174
212
  Type.Object({ t: Lit("state"), status: SessionStatusSchema }),
175
213
  Type.Object({ t: Lit("error"), code: Type.Union(ViewerErrorCodes.map((c) => Lit(c))), message: Type.String() }),
176
214
  Type.Object({ t: Lit("pong") }),
@@ -417,7 +455,9 @@ function parseAlertFragment(hash) {
417
455
  }
418
456
  export {
419
457
  EngineToViewerSchema,
458
+ FRAME_SEQ_MAX,
420
459
  FRAME_TYPE_JPEG,
460
+ FRAME_TYPE_JPEG_SEQ,
421
461
  FieldKinds,
422
462
  FieldSchema,
423
463
  KEY_SUBPROTOCOL_PREFIX,
@@ -455,5 +495,6 @@ export {
455
495
  parseViewerMessage,
456
496
  seal,
457
497
  sealAlert,
458
- sealMsg
498
+ sealMsg,
499
+ withFrameSeq
459
500
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@velmlabs/unstuck-protocol",
3
- "version": "0.2.0",
3
+ "version": "0.2.1",
4
4
  "description": "Wire protocol shared by the Unstuck engine, viewer and relays (frames, RPC, end-to-end encryption).",
5
5
  "keywords": [
6
6
  "ai",