@immediately-run/sdk 0.13.0 → 0.16.0

package/dist/protocolStream.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/protocolStream.ts"],"sourcesContent":["// SDK-side consumer for the host streaming transport (UI_AS_APPS_SPEC §5.1).\n//\n// The host `pumpGenerator` emits, per request msgId, a run of `stream.event`\n// frames terminated by one `stream.done` (with the return value) or `stream.error`\n// frame. This reassembles that run into an AsyncGenerator: each `event` is a\n// `yield`, the `done` value is the generator's `return`, an `error` is a `throw`.\n//\n// `consumeStream` takes an injected `StreamTransport` so it's unit-tested with a\n// fake send/subscribe — no bundler. `protocolStream`/`contribute` below wire it to\n// the real sandbox messageBus via sandboxUtils.\nimport { addListener, sendMessage } from './sandboxUtils';\n\nexport type StreamFrame =\n  | { kind: 'event'; value: unknown }\n  | { kind: 'done'; value: unknown }\n  | { kind: 'error'; code: string; message: string };\n\nexport interface StreamTransport {\n  // Fire the request that starts the stream. The host replies with frames tagged\n  // by the same `msgId`.\n  send: (msg: { type: string; method: string; params: unknown[]; msgId: number; stream: true }) => void;\n  // Subscribe to inbound frames for `type`; returns an unsubscribe.\n  subscribe: (\n    type: string,\n    handler: (msg: { msgId?: number; stream?: StreamFrame }) => void\n  ) => () => void;\n}\n\nexport class StreamError extends Error {\n  code: string;\n  constructor(code: string, message: string) {\n    super(message);\n    this.name = 'StreamError';\n    this.code = code;\n  }\n}\n\nlet streamCounter = 0;\nconst nextMsgId = (): number => {\n  // Distinct from the bundler's own protocolRequest counter space is unnecessary —\n  // frames are filtered by (type, msgId, stream) so a collision with a one-shot\n  // reply (which has `result`, not `stream`) can't be misread.\n  streamCounter = (streamCounter + 1) % Number.MAX_SAFE_INTEGER;\n  return streamCounter;\n};\n\n/**\n * Drive one streamed request to completion over an injected transport.\n *\n * Yields each event value; returns the `done` value; throws `StreamError` on an\n * error frame. Always unsubscribes (via the generator's `finally`) so an early\n * `break` in the consumer doesn't leak the listener.\n */\nexport async function* consumeStream<T = unknown, R = unknown>(\n  transport: StreamTransport,\n  type: string,\n  method: string,\n  params: unknown[],\n  msgId: number = nextMsgId()\n): AsyncGenerator<T, R, void> {\n  const queue: StreamFrame[] = [];\n  let wake: (() => void) | null = null;\n  const push = (frame: StreamFrame) => {\n    queue.push(frame);\n    const w = wake;\n    wake = null;\n    w?.();\n  };\n\n  const unsubscribe = transport.subscribe(type, (msg) => {\n    if (msg.msgId !== msgId || !msg.stream) return;\n    push(msg.stream);\n  });\n\n  try {\n    transport.send({ type, method, params, msgId, stream: true });\n    while (true) {\n      if (queue.length === 0) {\n        await new Promise<void>((resolve) => {\n          wake = resolve;\n        });\n        continue;\n      }\n      const frame = queue.shift() as StreamFrame;\n      if (frame.kind === 'event') {\n        yield frame.value as T;\n      } else if (frame.kind === 'done') {\n        return frame.value as R;\n      } else {\n        throw new StreamError(frame.code, frame.message);\n      }\n    }\n  } finally {\n    unsubscribe();\n  }\n}\n\n// The real sandbox transport, built from the bundler messageBus helpers.\nconst bundlerTransport: StreamTransport = {\n  send: (msg) => sendMessage(msg.type, msg as unknown as Record<string, unknown>),\n  subscribe: (type, handler) =>\n    addListener(type, (msg) => handler(msg as { msgId?: number; stream?: StreamFrame })),\n};\n\n/**\n * Consume an elevated streaming protocol method from app code.\n *\n * `for await (const ev of protocolStream('protocol-contribute', 'run', [opts])) …`\n */\nexport function protocolStream<T = unknown, R = unknown>(\n  protocolName: string,\n  method: string,\n  params: unknown[]\n): AsyncGenerator<T, R, void> {\n  return consumeStream<T, R>(bundlerTransport, protocolName, method, params);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAUA,0BAAyC;AAkBlC,MAAM,oBAAoB,MAAM;AAAA,EAErC,YAAY,MAAc,SAAiB;AACzC,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,OAAO;AAAA,EACd;AACF;AAEA,IAAI,gBAAgB;AACpB,MAAM,YAAY,MAAc;AAI9B,mBAAiB,gBAAgB,KAAK,OAAO;AAC7C,SAAO;AACT;AASA,gBAAuB,cACrB,WACA,MACA,QACA,QACA,QAAgB,UAAU,GACE;AAC5B,QAAM,QAAuB,CAAC;AAC9B,MAAI,OAA4B;AAChC,QAAM,OAAO,CAAC,UAAuB;AACnC,UAAM,KAAK,KAAK;AAChB,UAAM,IAAI;AACV,WAAO;AACP,QAAI;AAAA,EACN;AAEA,QAAM,cAAc,UAAU,UAAU,MAAM,CAAC,QAAQ;AACrD,QAAI,IAAI,UAAU,SAAS,CAAC,IAAI,OAAQ;AACxC,SAAK,IAAI,MAAM;AAAA,EACjB,CAAC;AAED,MAAI;AACF,cAAU,KAAK,EAAE,MAAM,QAAQ,QAAQ,OAAO,QAAQ,KAAK,CAAC;AAC5D,WAAO,MAAM;AACX,UAAI,MAAM,WAAW,GAAG;AACtB,cAAM,IAAI,QAAc,CAAC,YAAY;AACnC,iBAAO;AAAA,QACT,CAAC;AACD;AAAA,MACF;AACA,YAAM,QAAQ,MAAM,MAAM;AAC1B,UAAI,MAAM,SAAS,SAAS;AAC1B,cAAM,MAAM;AAAA,MACd,WAAW,MAAM,SAAS,QAAQ;AAChC,eAAO,MAAM;AAAA,MACf,OAAO;AACL,cAAM,IAAI,YAAY,MAAM,MAAM,MAAM,OAAO;AAAA,MACjD;AAAA,IACF;AAAA,EACF,UAAE;AACA,gBAAY;AAAA,EACd;AACF;AAGA,MAAM,mBAAoC;AAAA,EACxC,MAAM,CAAC,YAAQ,iCAAY,IAAI,MAAM,GAAyC;AAAA,EAC9E,WAAW,CAAC,MAAM,gBAChB,iCAAY,MAAM,CAAC,QAAQ,QAAQ,GAA+C,CAAC;AACvF;AAOO,SAAS,eACd,cACA,QACA,QAC4B;AAC5B,SAAO,cAAoB,kBAAkB,cAAc,QAAQ,MAAM;AAC3E;","names":[]}
+{"version":3,"sources":["../src/protocolStream.ts"],"sourcesContent":["// SDK-side consumer for the host streaming transport (UI_AS_APPS_SPEC §5.1).\n//\n// The host `pumpGenerator` emits, per request msgId, a run of `stream.event`\n// frames terminated by one `stream.done` (with the return value) or `stream.error`\n// frame. This reassembles that run into an AsyncGenerator: each `event` is a\n// `yield`, the `done` value is the generator's `return`, an `error` is a `throw`.\n//\n// `consumeStream` takes an injected `StreamTransport` so it's unit-tested with a\n// fake send/subscribe — no bundler. `protocolStream`/`contribute` below wire it to\n// the real sandbox messageBus via sandboxUtils.\nimport { addListener, sendMessage } from './sandboxUtils';\n\n/** One frame of a host stream: an `event` value, the terminal `done` value, or an `error`. */\nexport type StreamFrame =\n  | { kind: 'event'; value: unknown }\n  | { kind: 'done'; value: unknown }\n  | { kind: 'error'; code: string; message: string };\n\n/** The send/subscribe transport {@link consumeStream} drives (injected so it can be faked in tests). */\nexport interface StreamTransport {\n  // Fire the request that starts the stream. The host replies with frames tagged\n  // by the same `msgId`.\n  send: (msg: { type: string; method: string; params: unknown[]; msgId: number; stream: true }) => void;\n  // Subscribe to inbound frames for `type`; returns an unsubscribe.\n  subscribe: (\n    type: string,\n    handler: (msg: { msgId?: number; stream?: StreamFrame }) => void\n  ) => () => void;\n}\n\n/** Thrown when a stream ends in an `error` frame; carries the host's `code`. */\nexport class StreamError extends Error {\n  code: string;\n  constructor(code: string, message: string) {\n    super(message);\n    this.name = 'StreamError';\n    this.code = code;\n  }\n}\n\nlet streamCounter = 0;\nconst nextMsgId = (): number => {\n  // Distinct from the bundler's own protocolRequest counter space is unnecessary —\n  // frames are filtered by (type, msgId, stream) so a collision with a one-shot\n  // reply (which has `result`, not `stream`) can't be misread.\n  streamCounter = (streamCounter + 1) % Number.MAX_SAFE_INTEGER;\n  return streamCounter;\n};\n\n/**\n * Drive one streamed request to completion over an injected transport.\n *\n * Yields each event value; returns the `done` value; throws `StreamError` on an\n * error frame. Always unsubscribes (via the generator's `finally`) so an early\n * `break` in the consumer doesn't leak the listener.\n */\nexport async function* consumeStream<T = unknown, R = unknown>(\n  transport: StreamTransport,\n  type: string,\n  method: string,\n  params: unknown[],\n  msgId: number = nextMsgId()\n): AsyncGenerator<T, R, void> {\n  const queue: StreamFrame[] = [];\n  let wake: (() => void) | null = null;\n  const push = (frame: StreamFrame) => {\n    queue.push(frame);\n    const w = wake;\n    wake = null;\n    w?.();\n  };\n\n  const unsubscribe = transport.subscribe(type, (msg) => {\n    if (msg.msgId !== msgId || !msg.stream) return;\n    push(msg.stream);\n  });\n\n  try {\n    transport.send({ type, method, params, msgId, stream: true });\n    while (true) {\n      if (queue.length === 0) {\n        await new Promise<void>((resolve) => {\n          wake = resolve;\n        });\n        continue;\n      }\n      const frame = queue.shift() as StreamFrame;\n      if (frame.kind === 'event') {\n        yield frame.value as T;\n      } else if (frame.kind === 'done') {\n        return frame.value as R;\n      } else {\n        throw new StreamError(frame.code, frame.message);\n      }\n    }\n  } finally {\n    unsubscribe();\n  }\n}\n\n// The real sandbox transport, built from the bundler messageBus helpers.\nconst bundlerTransport: StreamTransport = {\n  send: (msg) => sendMessage(msg.type, msg as unknown as Record<string, unknown>),\n  subscribe: (type, handler) =>\n    addListener(type, (msg) => handler(msg as { msgId?: number; stream?: StreamFrame })),\n};\n\n/**\n * Consume an elevated streaming protocol method from app code.\n *\n * `for await (const ev of protocolStream('protocol-contribute', 'run', [opts])) …`\n */\nexport function protocolStream<T = unknown, R = unknown>(\n  protocolName: string,\n  method: string,\n  params: unknown[]\n): AsyncGenerator<T, R, void> {\n  return consumeStream<T, R>(bundlerTransport, protocolName, method, params);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAUA,0BAAyC;AAqBlC,MAAM,oBAAoB,MAAM;AAAA,EAErC,YAAY,MAAc,SAAiB;AACzC,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,OAAO;AAAA,EACd;AACF;AAEA,IAAI,gBAAgB;AACpB,MAAM,YAAY,MAAc;AAI9B,mBAAiB,gBAAgB,KAAK,OAAO;AAC7C,SAAO;AACT;AASA,gBAAuB,cACrB,WACA,MACA,QACA,QACA,QAAgB,UAAU,GACE;AAC5B,QAAM,QAAuB,CAAC;AAC9B,MAAI,OAA4B;AAChC,QAAM,OAAO,CAAC,UAAuB;AACnC,UAAM,KAAK,KAAK;AAChB,UAAM,IAAI;AACV,WAAO;AACP,QAAI;AAAA,EACN;AAEA,QAAM,cAAc,UAAU,UAAU,MAAM,CAAC,QAAQ;AACrD,QAAI,IAAI,UAAU,SAAS,CAAC,IAAI,OAAQ;AACxC,SAAK,IAAI,MAAM;AAAA,EACjB,CAAC;AAED,MAAI;AACF,cAAU,KAAK,EAAE,MAAM,QAAQ,QAAQ,OAAO,QAAQ,KAAK,CAAC;AAC5D,WAAO,MAAM;AACX,UAAI,MAAM,WAAW,GAAG;AACtB,cAAM,IAAI,QAAc,CAAC,YAAY;AACnC,iBAAO;AAAA,QACT,CAAC;AACD;AAAA,MACF;AACA,YAAM,QAAQ,MAAM,MAAM;AAC1B,UAAI,MAAM,SAAS,SAAS;AAC1B,cAAM,MAAM;AAAA,MACd,WAAW,MAAM,SAAS,QAAQ;AAChC,eAAO,MAAM;AAAA,MACf,OAAO;AACL,cAAM,IAAI,YAAY,MAAM,MAAM,MAAM,OAAO;AAAA,MACjD;AAAA,IACF;AAAA,EACF,UAAE;AACA,gBAAY;AAAA,EACd;AACF;AAGA,MAAM,mBAAoC;AAAA,EACxC,MAAM,CAAC,YAAQ,iCAAY,IAAI,MAAM,GAAyC;AAAA,EAC9E,WAAW,CAAC,MAAM,gBAChB,iCAAY,MAAM,CAAC,QAAQ,QAAQ,GAA+C,CAAC;AACvF;AAOO,SAAS,eACd,cACA,QACA,QAC4B;AAC5B,SAAO,cAAoB,kBAAkB,cAAc,QAAQ,MAAM;AAC3E;","names":[]}

package/dist/protocolStream.d.cts

@@ -1,3 +1,4 @@
+/** One frame of a host stream: an `event` value, the terminal `done` value, or an `error`. */
 type StreamFrame = {
     kind: 'event';
     value: unknown;
@@ -9,6 +10,7 @@ type StreamFrame = {
     code: string;
     message: string;
 };
+/** The send/subscribe transport {@link consumeStream} drives (injected so it can be faked in tests). */
 interface StreamTransport {
     send: (msg: {
         type: string;
@@ -22,6 +24,7 @@ interface StreamTransport {
         stream?: StreamFrame;
     }) => void) => () => void;
 }
+/** Thrown when a stream ends in an `error` frame; carries the host's `code`. */
 declare class StreamError extends Error {
     code: string;
     constructor(code: string, message: string);

package/dist/protocolStream.d.ts

@@ -1,3 +1,4 @@
+/** One frame of a host stream: an `event` value, the terminal `done` value, or an `error`. */
 type StreamFrame = {
     kind: 'event';
     value: unknown;
@@ -9,6 +10,7 @@ type StreamFrame = {
     code: string;
     message: string;
 };
+/** The send/subscribe transport {@link consumeStream} drives (injected so it can be faked in tests). */
 interface StreamTransport {
     send: (msg: {
         type: string;
@@ -22,6 +24,7 @@ interface StreamTransport {
         stream?: StreamFrame;
     }) => void) => () => void;
 }
+/** Thrown when a stream ends in an `error` frame; carries the host's `code`. */
 declare class StreamError extends Error {
     code: string;
     constructor(code: string, message: string);

package/dist/protocolStream.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/protocolStream.ts"],"sourcesContent":["// SDK-side consumer for the host streaming transport (UI_AS_APPS_SPEC §5.1).\n//\n// The host `pumpGenerator` emits, per request msgId, a run of `stream.event`\n// frames terminated by one `stream.done` (with the return value) or `stream.error`\n// frame. This reassembles that run into an AsyncGenerator: each `event` is a\n// `yield`, the `done` value is the generator's `return`, an `error` is a `throw`.\n//\n// `consumeStream` takes an injected `StreamTransport` so it's unit-tested with a\n// fake send/subscribe — no bundler. `protocolStream`/`contribute` below wire it to\n// the real sandbox messageBus via sandboxUtils.\nimport { addListener, sendMessage } from './sandboxUtils';\n\nexport type StreamFrame =\n  | { kind: 'event'; value: unknown }\n  | { kind: 'done'; value: unknown }\n  | { kind: 'error'; code: string; message: string };\n\nexport interface StreamTransport {\n  // Fire the request that starts the stream. The host replies with frames tagged\n  // by the same `msgId`.\n  send: (msg: { type: string; method: string; params: unknown[]; msgId: number; stream: true }) => void;\n  // Subscribe to inbound frames for `type`; returns an unsubscribe.\n  subscribe: (\n    type: string,\n    handler: (msg: { msgId?: number; stream?: StreamFrame }) => void\n  ) => () => void;\n}\n\nexport class StreamError extends Error {\n  code: string;\n  constructor(code: string, message: string) {\n    super(message);\n    this.name = 'StreamError';\n    this.code = code;\n  }\n}\n\nlet streamCounter = 0;\nconst nextMsgId = (): number => {\n  // Distinct from the bundler's own protocolRequest counter space is unnecessary —\n  // frames are filtered by (type, msgId, stream) so a collision with a one-shot\n  // reply (which has `result`, not `stream`) can't be misread.\n  streamCounter = (streamCounter + 1) % Number.MAX_SAFE_INTEGER;\n  return streamCounter;\n};\n\n/**\n * Drive one streamed request to completion over an injected transport.\n *\n * Yields each event value; returns the `done` value; throws `StreamError` on an\n * error frame. Always unsubscribes (via the generator's `finally`) so an early\n * `break` in the consumer doesn't leak the listener.\n */\nexport async function* consumeStream<T = unknown, R = unknown>(\n  transport: StreamTransport,\n  type: string,\n  method: string,\n  params: unknown[],\n  msgId: number = nextMsgId()\n): AsyncGenerator<T, R, void> {\n  const queue: StreamFrame[] = [];\n  let wake: (() => void) | null = null;\n  const push = (frame: StreamFrame) => {\n    queue.push(frame);\n    const w = wake;\n    wake = null;\n    w?.();\n  };\n\n  const unsubscribe = transport.subscribe(type, (msg) => {\n    if (msg.msgId !== msgId || !msg.stream) return;\n    push(msg.stream);\n  });\n\n  try {\n    transport.send({ type, method, params, msgId, stream: true });\n    while (true) {\n      if (queue.length === 0) {\n        await new Promise<void>((resolve) => {\n          wake = resolve;\n        });\n        continue;\n      }\n      const frame = queue.shift() as StreamFrame;\n      if (frame.kind === 'event') {\n        yield frame.value as T;\n      } else if (frame.kind === 'done') {\n        return frame.value as R;\n      } else {\n        throw new StreamError(frame.code, frame.message);\n      }\n    }\n  } finally {\n    unsubscribe();\n  }\n}\n\n// The real sandbox transport, built from the bundler messageBus helpers.\nconst bundlerTransport: StreamTransport = {\n  send: (msg) => sendMessage(msg.type, msg as unknown as Record<string, unknown>),\n  subscribe: (type, handler) =>\n    addListener(type, (msg) => handler(msg as { msgId?: number; stream?: StreamFrame })),\n};\n\n/**\n * Consume an elevated streaming protocol method from app code.\n *\n * `for await (const ev of protocolStream('protocol-contribute', 'run', [opts])) …`\n */\nexport function protocolStream<T = unknown, R = unknown>(\n  protocolName: string,\n  method: string,\n  params: unknown[]\n): AsyncGenerator<T, R, void> {\n  return consumeStream<T, R>(bundlerTransport, protocolName, method, params);\n}\n"],"mappings":"AAUA,SAAS,aAAa,mBAAmB;AAkBlC,MAAM,oBAAoB,MAAM;AAAA,EAErC,YAAY,MAAc,SAAiB;AACzC,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,OAAO;AAAA,EACd;AACF;AAEA,IAAI,gBAAgB;AACpB,MAAM,YAAY,MAAc;AAI9B,mBAAiB,gBAAgB,KAAK,OAAO;AAC7C,SAAO;AACT;AASA,gBAAuB,cACrB,WACA,MACA,QACA,QACA,QAAgB,UAAU,GACE;AAC5B,QAAM,QAAuB,CAAC;AAC9B,MAAI,OAA4B;AAChC,QAAM,OAAO,CAAC,UAAuB;AACnC,UAAM,KAAK,KAAK;AAChB,UAAM,IAAI;AACV,WAAO;AACP,QAAI;AAAA,EACN;AAEA,QAAM,cAAc,UAAU,UAAU,MAAM,CAAC,QAAQ;AACrD,QAAI,IAAI,UAAU,SAAS,CAAC,IAAI,OAAQ;AACxC,SAAK,IAAI,MAAM;AAAA,EACjB,CAAC;AAED,MAAI;AACF,cAAU,KAAK,EAAE,MAAM,QAAQ,QAAQ,OAAO,QAAQ,KAAK,CAAC;AAC5D,WAAO,MAAM;AACX,UAAI,MAAM,WAAW,GAAG;AACtB,cAAM,IAAI,QAAc,CAAC,YAAY;AACnC,iBAAO;AAAA,QACT,CAAC;AACD;AAAA,MACF;AACA,YAAM,QAAQ,MAAM,MAAM;AAC1B,UAAI,MAAM,SAAS,SAAS;AAC1B,cAAM,MAAM;AAAA,MACd,WAAW,MAAM,SAAS,QAAQ;AAChC,eAAO,MAAM;AAAA,MACf,OAAO;AACL,cAAM,IAAI,YAAY,MAAM,MAAM,MAAM,OAAO;AAAA,MACjD;AAAA,IACF;AAAA,EACF,UAAE;AACA,gBAAY;AAAA,EACd;AACF;AAGA,MAAM,mBAAoC;AAAA,EACxC,MAAM,CAAC,QAAQ,YAAY,IAAI,MAAM,GAAyC;AAAA,EAC9E,WAAW,CAAC,MAAM,YAChB,YAAY,MAAM,CAAC,QAAQ,QAAQ,GAA+C,CAAC;AACvF;AAOO,SAAS,eACd,cACA,QACA,QAC4B;AAC5B,SAAO,cAAoB,kBAAkB,cAAc,QAAQ,MAAM;AAC3E;","names":[]}
+{"version":3,"sources":["../src/protocolStream.ts"],"sourcesContent":["// SDK-side consumer for the host streaming transport (UI_AS_APPS_SPEC §5.1).\n//\n// The host `pumpGenerator` emits, per request msgId, a run of `stream.event`\n// frames terminated by one `stream.done` (with the return value) or `stream.error`\n// frame. This reassembles that run into an AsyncGenerator: each `event` is a\n// `yield`, the `done` value is the generator's `return`, an `error` is a `throw`.\n//\n// `consumeStream` takes an injected `StreamTransport` so it's unit-tested with a\n// fake send/subscribe — no bundler. `protocolStream`/`contribute` below wire it to\n// the real sandbox messageBus via sandboxUtils.\nimport { addListener, sendMessage } from './sandboxUtils';\n\n/** One frame of a host stream: an `event` value, the terminal `done` value, or an `error`. */\nexport type StreamFrame =\n  | { kind: 'event'; value: unknown }\n  | { kind: 'done'; value: unknown }\n  | { kind: 'error'; code: string; message: string };\n\n/** The send/subscribe transport {@link consumeStream} drives (injected so it can be faked in tests). */\nexport interface StreamTransport {\n  // Fire the request that starts the stream. The host replies with frames tagged\n  // by the same `msgId`.\n  send: (msg: { type: string; method: string; params: unknown[]; msgId: number; stream: true }) => void;\n  // Subscribe to inbound frames for `type`; returns an unsubscribe.\n  subscribe: (\n    type: string,\n    handler: (msg: { msgId?: number; stream?: StreamFrame }) => void\n  ) => () => void;\n}\n\n/** Thrown when a stream ends in an `error` frame; carries the host's `code`. */\nexport class StreamError extends Error {\n  code: string;\n  constructor(code: string, message: string) {\n    super(message);\n    this.name = 'StreamError';\n    this.code = code;\n  }\n}\n\nlet streamCounter = 0;\nconst nextMsgId = (): number => {\n  // Distinct from the bundler's own protocolRequest counter space is unnecessary —\n  // frames are filtered by (type, msgId, stream) so a collision with a one-shot\n  // reply (which has `result`, not `stream`) can't be misread.\n  streamCounter = (streamCounter + 1) % Number.MAX_SAFE_INTEGER;\n  return streamCounter;\n};\n\n/**\n * Drive one streamed request to completion over an injected transport.\n *\n * Yields each event value; returns the `done` value; throws `StreamError` on an\n * error frame. Always unsubscribes (via the generator's `finally`) so an early\n * `break` in the consumer doesn't leak the listener.\n */\nexport async function* consumeStream<T = unknown, R = unknown>(\n  transport: StreamTransport,\n  type: string,\n  method: string,\n  params: unknown[],\n  msgId: number = nextMsgId()\n): AsyncGenerator<T, R, void> {\n  const queue: StreamFrame[] = [];\n  let wake: (() => void) | null = null;\n  const push = (frame: StreamFrame) => {\n    queue.push(frame);\n    const w = wake;\n    wake = null;\n    w?.();\n  };\n\n  const unsubscribe = transport.subscribe(type, (msg) => {\n    if (msg.msgId !== msgId || !msg.stream) return;\n    push(msg.stream);\n  });\n\n  try {\n    transport.send({ type, method, params, msgId, stream: true });\n    while (true) {\n      if (queue.length === 0) {\n        await new Promise<void>((resolve) => {\n          wake = resolve;\n        });\n        continue;\n      }\n      const frame = queue.shift() as StreamFrame;\n      if (frame.kind === 'event') {\n        yield frame.value as T;\n      } else if (frame.kind === 'done') {\n        return frame.value as R;\n      } else {\n        throw new StreamError(frame.code, frame.message);\n      }\n    }\n  } finally {\n    unsubscribe();\n  }\n}\n\n// The real sandbox transport, built from the bundler messageBus helpers.\nconst bundlerTransport: StreamTransport = {\n  send: (msg) => sendMessage(msg.type, msg as unknown as Record<string, unknown>),\n  subscribe: (type, handler) =>\n    addListener(type, (msg) => handler(msg as { msgId?: number; stream?: StreamFrame })),\n};\n\n/**\n * Consume an elevated streaming protocol method from app code.\n *\n * `for await (const ev of protocolStream('protocol-contribute', 'run', [opts])) …`\n */\nexport function protocolStream<T = unknown, R = unknown>(\n  protocolName: string,\n  method: string,\n  params: unknown[]\n): AsyncGenerator<T, R, void> {\n  return consumeStream<T, R>(bundlerTransport, protocolName, method, params);\n}\n"],"mappings":"AAUA,SAAS,aAAa,mBAAmB;AAqBlC,MAAM,oBAAoB,MAAM;AAAA,EAErC,YAAY,MAAc,SAAiB;AACzC,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,OAAO;AAAA,EACd;AACF;AAEA,IAAI,gBAAgB;AACpB,MAAM,YAAY,MAAc;AAI9B,mBAAiB,gBAAgB,KAAK,OAAO;AAC7C,SAAO;AACT;AASA,gBAAuB,cACrB,WACA,MACA,QACA,QACA,QAAgB,UAAU,GACE;AAC5B,QAAM,QAAuB,CAAC;AAC9B,MAAI,OAA4B;AAChC,QAAM,OAAO,CAAC,UAAuB;AACnC,UAAM,KAAK,KAAK;AAChB,UAAM,IAAI;AACV,WAAO;AACP,QAAI;AAAA,EACN;AAEA,QAAM,cAAc,UAAU,UAAU,MAAM,CAAC,QAAQ;AACrD,QAAI,IAAI,UAAU,SAAS,CAAC,IAAI,OAAQ;AACxC,SAAK,IAAI,MAAM;AAAA,EACjB,CAAC;AAED,MAAI;AACF,cAAU,KAAK,EAAE,MAAM,QAAQ,QAAQ,OAAO,QAAQ,KAAK,CAAC;AAC5D,WAAO,MAAM;AACX,UAAI,MAAM,WAAW,GAAG;AACtB,cAAM,IAAI,QAAc,CAAC,YAAY;AACnC,iBAAO;AAAA,QACT,CAAC;AACD;AAAA,MACF;AACA,YAAM,QAAQ,MAAM,MAAM;AAC1B,UAAI,MAAM,SAAS,SAAS;AAC1B,cAAM,MAAM;AAAA,MACd,WAAW,MAAM,SAAS,QAAQ;AAChC,eAAO,MAAM;AAAA,MACf,OAAO;AACL,cAAM,IAAI,YAAY,MAAM,MAAM,MAAM,OAAO;AAAA,MACjD;AAAA,IACF;AAAA,EACF,UAAE;AACA,gBAAY;AAAA,EACd;AACF;AAGA,MAAM,mBAAoC;AAAA,EACxC,MAAM,CAAC,QAAQ,YAAY,IAAI,MAAM,GAAyC;AAAA,EAC9E,WAAW,CAAC,MAAM,YAChB,YAAY,MAAM,CAAC,QAAQ,QAAQ,GAA+C,CAAC;AACvF;AAOO,SAAS,eACd,cACA,QACA,QAC4B;AAC5B,SAAO,cAAoB,kBAAkB,cAAc,QAAQ,MAAM;AAC3E;","names":[]}

package/dist/ready.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/ready.ts"],"sourcesContent":["// The `ir.interactive` boot signal — the app-facing `reportReady()` / `onReady()` /\n// `getReadyState()` surface (LOAD_PROFILING_SPEC §3.1, R3-46). This closes the\n// \"existing SDK boot signal\" that `UI_AS_APPS_SPEC §6.2` referenced but never\n// defined.\n//\n// The runtime marks `ir.interactive` when the app's root render commits. An app\n// whose USEFULLY-interactive moment is later than first commit (e.g. after an\n// initial data load) calls `reportReady()` to DELAY the signal — which, per LP2-3,\n// can only ever push interactive later, never earlier than the commit (the host\n// resolves `max(commit, reportReady)`; see `resolveInteractive`). `onReady` /\n// `getReadyState` expose the report state in the same poll+subscribe shape as\n// `auth` / `mounts`.\n\nimport { sendMessage as defaultSend } from \"./sandboxUtils\";\n\nexport interface ReadyState {\n  /** Whether the app has called `reportReady()`. */\n  reported: boolean;\n  /** The app-reported timestamp (`performance.now()`), if it has reported. */\n  reportedAt?: number;\n}\n\ninterface ReadyDeps {\n  send: (type: string, data?: Record<string, unknown>) => void;\n  now: () => number;\n}\n\nconst realNow = (): number =>\n  typeof performance !== \"undefined\" && typeof performance.now === \"function\"\n    ? performance.now()\n    : Date.now();\n\nconst defaultDeps: ReadyDeps = { send: defaultSend, now: realNow };\n\nlet deps: ReadyDeps = defaultDeps;\nlet state: ReadyState = { reported: false };\nconst listeners = new Set<(s: ReadyState) => void>();\n\n/**\n * Signal that the app is usefully interactive (e.g. after an initial data load).\n * IDEMPOTENT — only the FIRST call counts; later calls are ignored. Forwards the\n * report to the runtime (`ir-report-ready`) so the host can resolve\n * `ir.interactive = max(rootRenderCommit, reportedAt)` (LP2-3) — calling it before\n * the root render commits can only delay the signal, never advance it.\n */\nexport function reportReady(): void {\n  if (state.reported) return;\n  state = { reported: true, reportedAt: deps.now() };\n  try {\n    deps.send(\"ir-report-ready\", { at: state.reportedAt });\n  } catch {\n    /* transport not ready — the runtime still marks interactive at root commit */\n  }\n  for (const l of listeners) l(state);\n}\n\n/** Pollable snapshot of the report state. */\nexport function getReadyState(): ReadyState {\n  return state;\n}\n\n/**\n * Subscribe to the ready signal. Invoked immediately with the current state (so a\n * late subscriber after `reportReady()` still fires) and again whenever it reports.\n * Returns an unsubscribe.\n */\nexport function onReady(listener: (s: ReadyState) => void): () => void {\n  listeners.add(listener);\n  listener(state);\n  return () => {\n    listeners.delete(listener);\n  };\n}\n\n/** Test seam: override the transport/clock. */\nexport function __setReadyDeps(d: Partial<ReadyDeps>): void {\n  deps = { ...defaultDeps, ...d };\n}\n\n/** Test seam: reset module state between cases. */\nexport function __resetReady(): void {\n  deps = defaultDeps;\n  state = { reported: false };\n  listeners.clear();\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAaA,0BAA2C;AAc3C,MAAM,UAAU,MACd,OAAO,gBAAgB,eAAe,OAAO,YAAY,QAAQ,aAC7D,YAAY,IAAI,IAChB,KAAK,IAAI;AAEf,MAAM,cAAyB,EAAE,MAAM,oBAAAA,aAAa,KAAK,QAAQ;AAEjE,IAAI,OAAkB;AACtB,IAAI,QAAoB,EAAE,UAAU,MAAM;AAC1C,MAAM,YAAY,oBAAI,IAA6B;AAS5C,SAAS,cAAoB;AAClC,MAAI,MAAM,SAAU;AACpB,UAAQ,EAAE,UAAU,MAAM,YAAY,KAAK,IAAI,EAAE;AACjD,MAAI;AACF,SAAK,KAAK,mBAAmB,EAAE,IAAI,MAAM,WAAW,CAAC;AAAA,EACvD,QAAQ;AAAA,EAER;AACA,aAAW,KAAK,UAAW,GAAE,KAAK;AACpC;AAGO,SAAS,gBAA4B;AAC1C,SAAO;AACT;AAOO,SAAS,QAAQ,UAA+C;AACrE,YAAU,IAAI,QAAQ;AACtB,WAAS,KAAK;AACd,SAAO,MAAM;AACX,cAAU,OAAO,QAAQ;AAAA,EAC3B;AACF;AAGO,SAAS,eAAe,GAA6B;AAC1D,SAAO,EAAE,GAAG,aAAa,GAAG,EAAE;AAChC;AAGO,SAAS,eAAqB;AACnC,SAAO;AACP,UAAQ,EAAE,UAAU,MAAM;AAC1B,YAAU,MAAM;AAClB;","names":["defaultSend"]}
+{"version":3,"sources":["../src/ready.ts"],"sourcesContent":["// The `ir.interactive` boot signal — the app-facing `reportReady()` / `onReady()` /\n// `getReadyState()` surface (LOAD_PROFILING_SPEC §3.1, R3-46). This closes the\n// \"existing SDK boot signal\" that `UI_AS_APPS_SPEC §6.2` referenced but never\n// defined.\n//\n// The runtime marks `ir.interactive` when the app's root render commits. An app\n// whose USEFULLY-interactive moment is later than first commit (e.g. after an\n// initial data load) calls `reportReady()` to DELAY the signal — which, per LP2-3,\n// can only ever push interactive later, never earlier than the commit (the host\n// resolves `max(commit, reportReady)`; see `resolveInteractive`). `onReady` /\n// `getReadyState` expose the report state in the same poll+subscribe shape as\n// `auth` / `mounts`.\n\nimport { sendMessage as defaultSend } from \"./sandboxUtils\";\n\n/** The app's `reportReady()` state, mirrored by {@link onReady}/{@link getReadyState}. */\nexport interface ReadyState {\n  /** Whether the app has called `reportReady()`. */\n  reported: boolean;\n  /** The app-reported timestamp (`performance.now()`), if it has reported. */\n  reportedAt?: number;\n}\n\ninterface ReadyDeps {\n  send: (type: string, data?: Record<string, unknown>) => void;\n  now: () => number;\n}\n\nconst realNow = (): number =>\n  typeof performance !== \"undefined\" && typeof performance.now === \"function\"\n    ? performance.now()\n    : Date.now();\n\nconst defaultDeps: ReadyDeps = { send: defaultSend, now: realNow };\n\nlet deps: ReadyDeps = defaultDeps;\nlet state: ReadyState = { reported: false };\nconst listeners = new Set<(s: ReadyState) => void>();\n\n/**\n * Signal that the app is usefully interactive (e.g. after an initial data load).\n * IDEMPOTENT — only the FIRST call counts; later calls are ignored. Forwards the\n * report to the runtime (`ir-report-ready`) so the host can resolve\n * `ir.interactive = max(rootRenderCommit, reportedAt)` (LP2-3) — calling it before\n * the root render commits can only delay the signal, never advance it.\n *\n * UX contract (LOADING_UX_SPEC §9.1): calling this tells the host *\"keep your\n * loading skeleton up; I am not done yet\"* — the host holds the §3 reveal until\n * this call (or the load budget). Call it ONCE, when the first USEFULLY-interactive\n * frame is on screen — not at mount, and not after every async settle. An app that\n * never calls it reveals automatically at the root-render commit (the default path).\n */\nexport function reportReady(): void {\n  if (state.reported) return;\n  state = { reported: true, reportedAt: deps.now() };\n  try {\n    deps.send(\"ir-report-ready\", { at: state.reportedAt });\n  } catch {\n    /* transport not ready — the runtime still marks interactive at root commit */\n  }\n  for (const l of listeners) l(state);\n}\n\n/** Pollable snapshot of the report state. */\nexport function getReadyState(): ReadyState {\n  return state;\n}\n\n/**\n * Subscribe to the ready signal. Invoked immediately with the current state (so a\n * late subscriber after `reportReady()` still fires) and again whenever it reports.\n * Returns an unsubscribe.\n */\nexport function onReady(listener: (s: ReadyState) => void): () => void {\n  listeners.add(listener);\n  listener(state);\n  return () => {\n    listeners.delete(listener);\n  };\n}\n\n/** Test seam: override the transport/clock. */\nexport function __setReadyDeps(d: Partial<ReadyDeps>): void {\n  deps = { ...defaultDeps, ...d };\n}\n\n/** Test seam: reset module state between cases. */\nexport function __resetReady(): void {\n  deps = defaultDeps;\n  state = { reported: false };\n  listeners.clear();\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAaA,0BAA2C;AAe3C,MAAM,UAAU,MACd,OAAO,gBAAgB,eAAe,OAAO,YAAY,QAAQ,aAC7D,YAAY,IAAI,IAChB,KAAK,IAAI;AAEf,MAAM,cAAyB,EAAE,MAAM,oBAAAA,aAAa,KAAK,QAAQ;AAEjE,IAAI,OAAkB;AACtB,IAAI,QAAoB,EAAE,UAAU,MAAM;AAC1C,MAAM,YAAY,oBAAI,IAA6B;AAe5C,SAAS,cAAoB;AAClC,MAAI,MAAM,SAAU;AACpB,UAAQ,EAAE,UAAU,MAAM,YAAY,KAAK,IAAI,EAAE;AACjD,MAAI;AACF,SAAK,KAAK,mBAAmB,EAAE,IAAI,MAAM,WAAW,CAAC;AAAA,EACvD,QAAQ;AAAA,EAER;AACA,aAAW,KAAK,UAAW,GAAE,KAAK;AACpC;AAGO,SAAS,gBAA4B;AAC1C,SAAO;AACT;AAOO,SAAS,QAAQ,UAA+C;AACrE,YAAU,IAAI,QAAQ;AACtB,WAAS,KAAK;AACd,SAAO,MAAM;AACX,cAAU,OAAO,QAAQ;AAAA,EAC3B;AACF;AAGO,SAAS,eAAe,GAA6B;AAC1D,SAAO,EAAE,GAAG,aAAa,GAAG,EAAE;AAChC;AAGO,SAAS,eAAqB;AACnC,SAAO;AACP,UAAQ,EAAE,UAAU,MAAM;AAC1B,YAAU,MAAM;AAClB;","names":["defaultSend"]}

package/dist/ready.d.cts

@@ -1,3 +1,4 @@
+/** The app's `reportReady()` state, mirrored by {@link onReady}/{@link getReadyState}. */
 interface ReadyState {
     /** Whether the app has called `reportReady()`. */
     reported: boolean;
@@ -14,6 +15,12 @@ interface ReadyDeps {
  * report to the runtime (`ir-report-ready`) so the host can resolve
  * `ir.interactive = max(rootRenderCommit, reportedAt)` (LP2-3) — calling it before
  * the root render commits can only delay the signal, never advance it.
+ *
+ * UX contract (LOADING_UX_SPEC §9.1): calling this tells the host *"keep your
+ * loading skeleton up; I am not done yet"* — the host holds the §3 reveal until
+ * this call (or the load budget). Call it ONCE, when the first USEFULLY-interactive
+ * frame is on screen — not at mount, and not after every async settle. An app that
+ * never calls it reveals automatically at the root-render commit (the default path).
  */
 declare function reportReady(): void;
 /** Pollable snapshot of the report state. */

package/dist/ready.d.ts

@@ -1,3 +1,4 @@
+/** The app's `reportReady()` state, mirrored by {@link onReady}/{@link getReadyState}. */
 interface ReadyState {
     /** Whether the app has called `reportReady()`. */
     reported: boolean;
@@ -14,6 +15,12 @@ interface ReadyDeps {
  * report to the runtime (`ir-report-ready`) so the host can resolve
  * `ir.interactive = max(rootRenderCommit, reportedAt)` (LP2-3) — calling it before
  * the root render commits can only delay the signal, never advance it.
+ *
+ * UX contract (LOADING_UX_SPEC §9.1): calling this tells the host *"keep your
+ * loading skeleton up; I am not done yet"* — the host holds the §3 reveal until
+ * this call (or the load budget). Call it ONCE, when the first USEFULLY-interactive
+ * frame is on screen — not at mount, and not after every async settle. An app that
+ * never calls it reveals automatically at the root-render commit (the default path).
  */
 declare function reportReady(): void;
 /** Pollable snapshot of the report state. */

package/dist/ready.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/ready.ts"],"sourcesContent":["// The `ir.interactive` boot signal — the app-facing `reportReady()` / `onReady()` /\n// `getReadyState()` surface (LOAD_PROFILING_SPEC §3.1, R3-46). This closes the\n// \"existing SDK boot signal\" that `UI_AS_APPS_SPEC §6.2` referenced but never\n// defined.\n//\n// The runtime marks `ir.interactive` when the app's root render commits. An app\n// whose USEFULLY-interactive moment is later than first commit (e.g. after an\n// initial data load) calls `reportReady()` to DELAY the signal — which, per LP2-3,\n// can only ever push interactive later, never earlier than the commit (the host\n// resolves `max(commit, reportReady)`; see `resolveInteractive`). `onReady` /\n// `getReadyState` expose the report state in the same poll+subscribe shape as\n// `auth` / `mounts`.\n\nimport { sendMessage as defaultSend } from \"./sandboxUtils\";\n\nexport interface ReadyState {\n  /** Whether the app has called `reportReady()`. */\n  reported: boolean;\n  /** The app-reported timestamp (`performance.now()`), if it has reported. */\n  reportedAt?: number;\n}\n\ninterface ReadyDeps {\n  send: (type: string, data?: Record<string, unknown>) => void;\n  now: () => number;\n}\n\nconst realNow = (): number =>\n  typeof performance !== \"undefined\" && typeof performance.now === \"function\"\n    ? performance.now()\n    : Date.now();\n\nconst defaultDeps: ReadyDeps = { send: defaultSend, now: realNow };\n\nlet deps: ReadyDeps = defaultDeps;\nlet state: ReadyState = { reported: false };\nconst listeners = new Set<(s: ReadyState) => void>();\n\n/**\n * Signal that the app is usefully interactive (e.g. after an initial data load).\n * IDEMPOTENT — only the FIRST call counts; later calls are ignored. Forwards the\n * report to the runtime (`ir-report-ready`) so the host can resolve\n * `ir.interactive = max(rootRenderCommit, reportedAt)` (LP2-3) — calling it before\n * the root render commits can only delay the signal, never advance it.\n */\nexport function reportReady(): void {\n  if (state.reported) return;\n  state = { reported: true, reportedAt: deps.now() };\n  try {\n    deps.send(\"ir-report-ready\", { at: state.reportedAt });\n  } catch {\n    /* transport not ready — the runtime still marks interactive at root commit */\n  }\n  for (const l of listeners) l(state);\n}\n\n/** Pollable snapshot of the report state. */\nexport function getReadyState(): ReadyState {\n  return state;\n}\n\n/**\n * Subscribe to the ready signal. Invoked immediately with the current state (so a\n * late subscriber after `reportReady()` still fires) and again whenever it reports.\n * Returns an unsubscribe.\n */\nexport function onReady(listener: (s: ReadyState) => void): () => void {\n  listeners.add(listener);\n  listener(state);\n  return () => {\n    listeners.delete(listener);\n  };\n}\n\n/** Test seam: override the transport/clock. */\nexport function __setReadyDeps(d: Partial<ReadyDeps>): void {\n  deps = { ...defaultDeps, ...d };\n}\n\n/** Test seam: reset module state between cases. */\nexport function __resetReady(): void {\n  deps = defaultDeps;\n  state = { reported: false };\n  listeners.clear();\n}\n"],"mappings":"AAaA,SAAS,eAAe,mBAAmB;AAc3C,MAAM,UAAU,MACd,OAAO,gBAAgB,eAAe,OAAO,YAAY,QAAQ,aAC7D,YAAY,IAAI,IAChB,KAAK,IAAI;AAEf,MAAM,cAAyB,EAAE,MAAM,aAAa,KAAK,QAAQ;AAEjE,IAAI,OAAkB;AACtB,IAAI,QAAoB,EAAE,UAAU,MAAM;AAC1C,MAAM,YAAY,oBAAI,IAA6B;AAS5C,SAAS,cAAoB;AAClC,MAAI,MAAM,SAAU;AACpB,UAAQ,EAAE,UAAU,MAAM,YAAY,KAAK,IAAI,EAAE;AACjD,MAAI;AACF,SAAK,KAAK,mBAAmB,EAAE,IAAI,MAAM,WAAW,CAAC;AAAA,EACvD,QAAQ;AAAA,EAER;AACA,aAAW,KAAK,UAAW,GAAE,KAAK;AACpC;AAGO,SAAS,gBAA4B;AAC1C,SAAO;AACT;AAOO,SAAS,QAAQ,UAA+C;AACrE,YAAU,IAAI,QAAQ;AACtB,WAAS,KAAK;AACd,SAAO,MAAM;AACX,cAAU,OAAO,QAAQ;AAAA,EAC3B;AACF;AAGO,SAAS,eAAe,GAA6B;AAC1D,SAAO,EAAE,GAAG,aAAa,GAAG,EAAE;AAChC;AAGO,SAAS,eAAqB;AACnC,SAAO;AACP,UAAQ,EAAE,UAAU,MAAM;AAC1B,YAAU,MAAM;AAClB;","names":[]}
+{"version":3,"sources":["../src/ready.ts"],"sourcesContent":["// The `ir.interactive` boot signal — the app-facing `reportReady()` / `onReady()` /\n// `getReadyState()` surface (LOAD_PROFILING_SPEC §3.1, R3-46). This closes the\n// \"existing SDK boot signal\" that `UI_AS_APPS_SPEC §6.2` referenced but never\n// defined.\n//\n// The runtime marks `ir.interactive` when the app's root render commits. An app\n// whose USEFULLY-interactive moment is later than first commit (e.g. after an\n// initial data load) calls `reportReady()` to DELAY the signal — which, per LP2-3,\n// can only ever push interactive later, never earlier than the commit (the host\n// resolves `max(commit, reportReady)`; see `resolveInteractive`). `onReady` /\n// `getReadyState` expose the report state in the same poll+subscribe shape as\n// `auth` / `mounts`.\n\nimport { sendMessage as defaultSend } from \"./sandboxUtils\";\n\n/** The app's `reportReady()` state, mirrored by {@link onReady}/{@link getReadyState}. */\nexport interface ReadyState {\n  /** Whether the app has called `reportReady()`. */\n  reported: boolean;\n  /** The app-reported timestamp (`performance.now()`), if it has reported. */\n  reportedAt?: number;\n}\n\ninterface ReadyDeps {\n  send: (type: string, data?: Record<string, unknown>) => void;\n  now: () => number;\n}\n\nconst realNow = (): number =>\n  typeof performance !== \"undefined\" && typeof performance.now === \"function\"\n    ? performance.now()\n    : Date.now();\n\nconst defaultDeps: ReadyDeps = { send: defaultSend, now: realNow };\n\nlet deps: ReadyDeps = defaultDeps;\nlet state: ReadyState = { reported: false };\nconst listeners = new Set<(s: ReadyState) => void>();\n\n/**\n * Signal that the app is usefully interactive (e.g. after an initial data load).\n * IDEMPOTENT — only the FIRST call counts; later calls are ignored. Forwards the\n * report to the runtime (`ir-report-ready`) so the host can resolve\n * `ir.interactive = max(rootRenderCommit, reportedAt)` (LP2-3) — calling it before\n * the root render commits can only delay the signal, never advance it.\n *\n * UX contract (LOADING_UX_SPEC §9.1): calling this tells the host *\"keep your\n * loading skeleton up; I am not done yet\"* — the host holds the §3 reveal until\n * this call (or the load budget). Call it ONCE, when the first USEFULLY-interactive\n * frame is on screen — not at mount, and not after every async settle. An app that\n * never calls it reveals automatically at the root-render commit (the default path).\n */\nexport function reportReady(): void {\n  if (state.reported) return;\n  state = { reported: true, reportedAt: deps.now() };\n  try {\n    deps.send(\"ir-report-ready\", { at: state.reportedAt });\n  } catch {\n    /* transport not ready — the runtime still marks interactive at root commit */\n  }\n  for (const l of listeners) l(state);\n}\n\n/** Pollable snapshot of the report state. */\nexport function getReadyState(): ReadyState {\n  return state;\n}\n\n/**\n * Subscribe to the ready signal. Invoked immediately with the current state (so a\n * late subscriber after `reportReady()` still fires) and again whenever it reports.\n * Returns an unsubscribe.\n */\nexport function onReady(listener: (s: ReadyState) => void): () => void {\n  listeners.add(listener);\n  listener(state);\n  return () => {\n    listeners.delete(listener);\n  };\n}\n\n/** Test seam: override the transport/clock. */\nexport function __setReadyDeps(d: Partial<ReadyDeps>): void {\n  deps = { ...defaultDeps, ...d };\n}\n\n/** Test seam: reset module state between cases. */\nexport function __resetReady(): void {\n  deps = defaultDeps;\n  state = { reported: false };\n  listeners.clear();\n}\n"],"mappings":"AAaA,SAAS,eAAe,mBAAmB;AAe3C,MAAM,UAAU,MACd,OAAO,gBAAgB,eAAe,OAAO,YAAY,QAAQ,aAC7D,YAAY,IAAI,IAChB,KAAK,IAAI;AAEf,MAAM,cAAyB,EAAE,MAAM,aAAa,KAAK,QAAQ;AAEjE,IAAI,OAAkB;AACtB,IAAI,QAAoB,EAAE,UAAU,MAAM;AAC1C,MAAM,YAAY,oBAAI,IAA6B;AAe5C,SAAS,cAAoB;AAClC,MAAI,MAAM,SAAU;AACpB,UAAQ,EAAE,UAAU,MAAM,YAAY,KAAK,IAAI,EAAE;AACjD,MAAI;AACF,SAAK,KAAK,mBAAmB,EAAE,IAAI,MAAM,WAAW,CAAC;AAAA,EACvD,QAAQ;AAAA,EAER;AACA,aAAW,KAAK,UAAW,GAAE,KAAK;AACpC;AAGO,SAAS,gBAA4B;AAC1C,SAAO;AACT;AAOO,SAAS,QAAQ,UAA+C;AACrE,YAAU,IAAI,QAAQ;AACtB,WAAS,KAAK;AACd,SAAO,MAAM;AACX,cAAU,OAAO,QAAQ;AAAA,EAC3B;AACF;AAGO,SAAS,eAAe,GAA6B;AAC1D,SAAO,EAAE,GAAG,aAAa,GAAG,EAAE;AAChC;AAGO,SAAS,eAAqB;AACnC,SAAO;AACP,UAAQ,EAAE,UAAU,MAAM;AAC1B,YAAU,MAAM;AAClB;","names":[]}

package/dist/routeMatch.cjs

@@ -0,0 +1,72 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var routeMatch_exports = {};
+__export(routeMatch_exports, {
+  compileTemplate: () => compileTemplate,
+  matchRoute: () => matchRoute,
+  toRegExp: () => toRegExp
+});
+module.exports = __toCommonJS(routeMatch_exports);
+const escapeForRegexp = (str) => str.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&");
+const WILDCARD_GROUP = "wild";
+const compileTemplate = (template) => {
+  const token = /(:[A-Za-z_][A-Za-z0-9_]*)|\*/g;
+  let src = "";
+  let last = 0;
+  let m;
+  while ((m = token.exec(template)) !== null) {
+    src += escapeForRegexp(template.slice(last, m.index));
+    src += m[1] ? `(?<${m[1].slice(1)}>[^/]+)` : `(?<${WILDCARD_GROUP}>.*)`;
+    last = m.index + m[0].length;
+  }
+  src += escapeForRegexp(template.slice(last));
+  return new RegExp(`^${src}$`);
+};
+const templateCache = /* @__PURE__ */ new Map();
+const toRegExp = (pattern) => {
+  if (pattern instanceof RegExp) {
+    return pattern;
+  }
+  let compiled = templateCache.get(pattern);
+  if (!compiled) {
+    compiled = compileTemplate(pattern);
+    templateCache.set(pattern, compiled);
+  }
+  return compiled;
+};
+const matchRoute = (pattern, path) => {
+  const match = path.match(toRegExp(pattern));
+  if (!match) {
+    return null;
+  }
+  const params = {};
+  for (const [key, value] of Object.entries(match.groups ?? {})) {
+    if (value !== void 0) {
+      params[key === WILDCARD_GROUP ? "*" : key] = value;
+    }
+  }
+  return params;
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  compileTemplate,
+  matchRoute,
+  toRegExp
+});
+//# sourceMappingURL=routeMatch.cjs.map

package/dist/routeMatch.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/routeMatch.ts"],"sourcesContent":["import type { RouteParams } from './RoutingSpec';\n\n// from: https://stackoverflow.com/a/63838890\nconst escapeForRegexp = (str: string): string => str.replace(/[.*+\\-?^${}()|[\\]\\\\]/g, '\\\\$&');\n\n// Internal group name standing in for a `*` wildcard (which is not a valid JS\n// regex group identifier); remapped to the `*` param key after matching.\nconst WILDCARD_GROUP = 'wild';\n\n/**\n * Compile a path template to an anchored RegExp with named groups:\n *   `:name` → one non-slash segment   `*` → the rest (greedy)\n * A template with neither token is a literal exact match. Raw RegExp patterns\n * never reach here — they are the escape hatch, used as authored.\n */\nexport const compileTemplate = (template: string): RegExp => {\n  const token = /(:[A-Za-z_][A-Za-z0-9_]*)|\\*/g;\n  let src = '';\n  let last = 0;\n  let m: RegExpExecArray | null;\n  while ((m = token.exec(template)) !== null) {\n    src += escapeForRegexp(template.slice(last, m.index));\n    src += m[1] ? `(?<${m[1].slice(1)}>[^/]+)` : `(?<${WILDCARD_GROUP}>.*)`;\n    last = m.index + m[0].length;\n  }\n  src += escapeForRegexp(template.slice(last));\n  return new RegExp(`^${src}$`);\n};\n\nconst templateCache = new Map<string, RegExp>();\n\n/** Resolve a pattern to a RegExp: templates are compiled (and cached), RegExp passes through. */\nexport const toRegExp = (pattern: string | RegExp): RegExp => {\n  if (pattern instanceof RegExp) {\n    return pattern;\n  }\n  let compiled = templateCache.get(pattern);\n  if (!compiled) {\n    compiled = compileTemplate(pattern);\n    templateCache.set(pattern, compiled);\n  }\n  return compiled;\n};\n\n/**\n * Match a `sandboxPath` against a route pattern. Returns the named params on a\n * match (the `*` wildcard surfaces under the `'*'` key), or `null` otherwise.\n */\nexport const matchRoute = (pattern: string | RegExp, path: string): RouteParams | null => {\n  const match = path.match(toRegExp(pattern));\n  if (!match) {\n    return null;\n  }\n  const params: RouteParams = {};\n  for (const [key, value] of Object.entries(match.groups ?? {})) {\n    if (value !== undefined) {\n      params[key === WILDCARD_GROUP ? '*' : key] = value;\n    }\n  }\n  return params;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAGA,MAAM,kBAAkB,CAAC,QAAwB,IAAI,QAAQ,yBAAyB,MAAM;AAI5F,MAAM,iBAAiB;AAQhB,MAAM,kBAAkB,CAAC,aAA6B;AAC3D,QAAM,QAAQ;AACd,MAAI,MAAM;AACV,MAAI,OAAO;AACX,MAAI;AACJ,UAAQ,IAAI,MAAM,KAAK,QAAQ,OAAO,MAAM;AAC1C,WAAO,gBAAgB,SAAS,MAAM,MAAM,EAAE,KAAK,CAAC;AACpD,WAAO,EAAE,CAAC,IAAI,MAAM,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,YAAY,MAAM,cAAc;AACjE,WAAO,EAAE,QAAQ,EAAE,CAAC,EAAE;AAAA,EACxB;AACA,SAAO,gBAAgB,SAAS,MAAM,IAAI,CAAC;AAC3C,SAAO,IAAI,OAAO,IAAI,GAAG,GAAG;AAC9B;AAEA,MAAM,gBAAgB,oBAAI,IAAoB;AAGvC,MAAM,WAAW,CAAC,YAAqC;AAC5D,MAAI,mBAAmB,QAAQ;AAC7B,WAAO;AAAA,EACT;AACA,MAAI,WAAW,cAAc,IAAI,OAAO;AACxC,MAAI,CAAC,UAAU;AACb,eAAW,gBAAgB,OAAO;AAClC,kBAAc,IAAI,SAAS,QAAQ;AAAA,EACrC;AACA,SAAO;AACT;AAMO,MAAM,aAAa,CAAC,SAA0B,SAAqC;AACxF,QAAM,QAAQ,KAAK,MAAM,SAAS,OAAO,CAAC;AAC1C,MAAI,CAAC,OAAO;AACV,WAAO;AAAA,EACT;AACA,QAAM,SAAsB,CAAC;AAC7B,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,MAAM,UAAU,CAAC,CAAC,GAAG;AAC7D,QAAI,UAAU,QAAW;AACvB,aAAO,QAAQ,iBAAiB,MAAM,GAAG,IAAI;AAAA,IAC/C;AAAA,EACF;AACA,SAAO;AACT;","names":[]}

package/dist/routeMatch.d.cts

@@ -0,0 +1,19 @@
+import { RouteParams } from './RoutingSpec.cjs';
+import 'react';
+
+/**
+ * Compile a path template to an anchored RegExp with named groups:
+ *   `:name` → one non-slash segment   `*` → the rest (greedy)
+ * A template with neither token is a literal exact match. Raw RegExp patterns
+ * never reach here — they are the escape hatch, used as authored.
+ */
+declare const compileTemplate: (template: string) => RegExp;
+/** Resolve a pattern to a RegExp: templates are compiled (and cached), RegExp passes through. */
+declare const toRegExp: (pattern: string | RegExp) => RegExp;
+/**
+ * Match a `sandboxPath` against a route pattern. Returns the named params on a
+ * match (the `*` wildcard surfaces under the `'*'` key), or `null` otherwise.
+ */
+declare const matchRoute: (pattern: string | RegExp, path: string) => RouteParams | null;
+
+export { compileTemplate, matchRoute, toRegExp };

package/dist/routeMatch.d.ts

@@ -0,0 +1,19 @@
+import { RouteParams } from './RoutingSpec.js';
+import 'react';
+
+/**
+ * Compile a path template to an anchored RegExp with named groups:
+ *   `:name` → one non-slash segment   `*` → the rest (greedy)
+ * A template with neither token is a literal exact match. Raw RegExp patterns
+ * never reach here — they are the escape hatch, used as authored.
+ */
+declare const compileTemplate: (template: string) => RegExp;
+/** Resolve a pattern to a RegExp: templates are compiled (and cached), RegExp passes through. */
+declare const toRegExp: (pattern: string | RegExp) => RegExp;
+/**
+ * Match a `sandboxPath` against a route pattern. Returns the named params on a
+ * match (the `*` wildcard surfaces under the `'*'` key), or `null` otherwise.
+ */
+declare const matchRoute: (pattern: string | RegExp, path: string) => RouteParams | null;
+
+export { compileTemplate, matchRoute, toRegExp };

package/dist/routeMatch.js

@@ -0,0 +1,46 @@
+const escapeForRegexp = (str) => str.replace(/[.*+\-?^${}()|[\]\\]/g, "\\$&");
+const WILDCARD_GROUP = "wild";
+const compileTemplate = (template) => {
+  const token = /(:[A-Za-z_][A-Za-z0-9_]*)|\*/g;
+  let src = "";
+  let last = 0;
+  let m;
+  while ((m = token.exec(template)) !== null) {
+    src += escapeForRegexp(template.slice(last, m.index));
+    src += m[1] ? `(?<${m[1].slice(1)}>[^/]+)` : `(?<${WILDCARD_GROUP}>.*)`;
+    last = m.index + m[0].length;
+  }
+  src += escapeForRegexp(template.slice(last));
+  return new RegExp(`^${src}$`);
+};
+const templateCache = /* @__PURE__ */ new Map();
+const toRegExp = (pattern) => {
+  if (pattern instanceof RegExp) {
+    return pattern;
+  }
+  let compiled = templateCache.get(pattern);
+  if (!compiled) {
+    compiled = compileTemplate(pattern);
+    templateCache.set(pattern, compiled);
+  }
+  return compiled;
+};
+const matchRoute = (pattern, path) => {
+  const match = path.match(toRegExp(pattern));
+  if (!match) {
+    return null;
+  }
+  const params = {};
+  for (const [key, value] of Object.entries(match.groups ?? {})) {
+    if (value !== void 0) {
+      params[key === WILDCARD_GROUP ? "*" : key] = value;
+    }
+  }
+  return params;
+};
+export {
+  compileTemplate,
+  matchRoute,
+  toRegExp
+};
+//# sourceMappingURL=routeMatch.js.map

package/dist/routeMatch.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/routeMatch.ts"],"sourcesContent":["import type { RouteParams } from './RoutingSpec';\n\n// from: https://stackoverflow.com/a/63838890\nconst escapeForRegexp = (str: string): string => str.replace(/[.*+\\-?^${}()|[\\]\\\\]/g, '\\\\$&');\n\n// Internal group name standing in for a `*` wildcard (which is not a valid JS\n// regex group identifier); remapped to the `*` param key after matching.\nconst WILDCARD_GROUP = 'wild';\n\n/**\n * Compile a path template to an anchored RegExp with named groups:\n *   `:name` → one non-slash segment   `*` → the rest (greedy)\n * A template with neither token is a literal exact match. Raw RegExp patterns\n * never reach here — they are the escape hatch, used as authored.\n */\nexport const compileTemplate = (template: string): RegExp => {\n  const token = /(:[A-Za-z_][A-Za-z0-9_]*)|\\*/g;\n  let src = '';\n  let last = 0;\n  let m: RegExpExecArray | null;\n  while ((m = token.exec(template)) !== null) {\n    src += escapeForRegexp(template.slice(last, m.index));\n    src += m[1] ? `(?<${m[1].slice(1)}>[^/]+)` : `(?<${WILDCARD_GROUP}>.*)`;\n    last = m.index + m[0].length;\n  }\n  src += escapeForRegexp(template.slice(last));\n  return new RegExp(`^${src}$`);\n};\n\nconst templateCache = new Map<string, RegExp>();\n\n/** Resolve a pattern to a RegExp: templates are compiled (and cached), RegExp passes through. */\nexport const toRegExp = (pattern: string | RegExp): RegExp => {\n  if (pattern instanceof RegExp) {\n    return pattern;\n  }\n  let compiled = templateCache.get(pattern);\n  if (!compiled) {\n    compiled = compileTemplate(pattern);\n    templateCache.set(pattern, compiled);\n  }\n  return compiled;\n};\n\n/**\n * Match a `sandboxPath` against a route pattern. Returns the named params on a\n * match (the `*` wildcard surfaces under the `'*'` key), or `null` otherwise.\n */\nexport const matchRoute = (pattern: string | RegExp, path: string): RouteParams | null => {\n  const match = path.match(toRegExp(pattern));\n  if (!match) {\n    return null;\n  }\n  const params: RouteParams = {};\n  for (const [key, value] of Object.entries(match.groups ?? {})) {\n    if (value !== undefined) {\n      params[key === WILDCARD_GROUP ? '*' : key] = value;\n    }\n  }\n  return params;\n};\n"],"mappings":"AAGA,MAAM,kBAAkB,CAAC,QAAwB,IAAI,QAAQ,yBAAyB,MAAM;AAI5F,MAAM,iBAAiB;AAQhB,MAAM,kBAAkB,CAAC,aAA6B;AAC3D,QAAM,QAAQ;AACd,MAAI,MAAM;AACV,MAAI,OAAO;AACX,MAAI;AACJ,UAAQ,IAAI,MAAM,KAAK,QAAQ,OAAO,MAAM;AAC1C,WAAO,gBAAgB,SAAS,MAAM,MAAM,EAAE,KAAK,CAAC;AACpD,WAAO,EAAE,CAAC,IAAI,MAAM,EAAE,CAAC,EAAE,MAAM,CAAC,CAAC,YAAY,MAAM,cAAc;AACjE,WAAO,EAAE,QAAQ,EAAE,CAAC,EAAE;AAAA,EACxB;AACA,SAAO,gBAAgB,SAAS,MAAM,IAAI,CAAC;AAC3C,SAAO,IAAI,OAAO,IAAI,GAAG,GAAG;AAC9B;AAEA,MAAM,gBAAgB,oBAAI,IAAoB;AAGvC,MAAM,WAAW,CAAC,YAAqC;AAC5D,MAAI,mBAAmB,QAAQ;AAC7B,WAAO;AAAA,EACT;AACA,MAAI,WAAW,cAAc,IAAI,OAAO;AACxC,MAAI,CAAC,UAAU;AACb,eAAW,gBAAgB,OAAO;AAClC,kBAAc,IAAI,SAAS,QAAQ;AAAA,EACrC;AACA,SAAO;AACT;AAMO,MAAM,aAAa,CAAC,SAA0B,SAAqC;AACxF,QAAM,QAAQ,KAAK,MAAM,SAAS,OAAO,CAAC;AAC1C,MAAI,CAAC,OAAO;AACV,WAAO;AAAA,EACT;AACA,QAAM,SAAsB,CAAC;AAC7B,aAAW,CAAC,KAAK,KAAK,KAAK,OAAO,QAAQ,MAAM,UAAU,CAAC,CAAC,GAAG;AAC7D,QAAI,UAAU,QAAW;AACvB,aAAO,QAAQ,iBAAiB,MAAM,GAAG,IAAI;AAAA,IAC/C;AAAA,EACF;AACA,SAAO;AACT;","names":[]}

package/dist/routing.cjs

@@ -21,12 +21,17 @@ __export(routing_exports, {
   Router: () => Router,
   applyRoutingRule: () => applyRoutingRule,
   navigate: () => navigate,
+  renderRoute: () => renderRoute,
+  useRoute: () => useRoute,
+  useRouteParams: () => useRouteParams,
   useTinkerableLink: () => useTinkerableLink
 });
 module.exports = __toCommonJS(routing_exports);
+var import_jsx_runtime = require("react/jsx-runtime");
 var import_react = require("react");
 var import_sandboxUtils = require("./sandboxUtils");
 var import_TinkerableContext = require("./TinkerableContext");
+var import_routeMatch = require("./routeMatch");
 var import_urlUtils = require("./urlUtils");
 var import_pathUtils = require("./pathUtils");
 const useTinkerableLink = (newSandboxLocation) => {
@@ -42,29 +47,42 @@ const useTinkerableLink = (newSandboxLocation) => {
 const applyRoutingRule = (routingSpec, navigationState) => {
   const { sandboxPath } = navigationState;
   for (const routingRule of routingSpec.routes) {
-    if (typeof routingRule.pattern === "string") {
-      if (routingRule.pattern === sandboxPath) {
-        return { routingRule };
-      }
-    } else {
-      const match = sandboxPath.match(routingRule.pattern);
-      if (routingRule.pattern.test(sandboxPath)) {
-        return {
-          routingRule,
-          pathParameters: match?.groups
-        };
-      }
+    const pathParameters = (0, import_routeMatch.matchRoute)(routingRule.pattern, sandboxPath);
+    if (pathParameters) {
+      return { routingRule, pathParameters };
     }
   }
   return void 0;
 };
+const renderRoute = (routingRule, params) => {
+  if (routingRule.component) {
+    const Component = routingRule.component;
+    return /* @__PURE__ */ (0, import_jsx_runtime.jsx)(Component, { params });
+  }
+  return routingRule.element ?? routingRule.reactNode ?? null;
+};
 const Router = () => {
   const context = (0, import_react.useContext)(import_TinkerableContext.TinkerableContext);
-  const { navigationState: { routingRule } } = context;
+  const { navigationState: { routingRule, pathParameters } } = context;
   if (!routingRule) {
     throw new Error(`No route registered for path ${context.navigationState.sandboxPath}!`);
   }
-  return routingRule.reactNode;
+  return renderRoute(routingRule, pathParameters ?? {});
+};
+const useRouteParams = () => (0, import_react.use)(import_TinkerableContext.TinkerableContext).navigationState.pathParameters ?? {};
+const useRoute = () => {
+  const { navigationState } = (0, import_react.use)(import_TinkerableContext.TinkerableContext);
+  const { routingRule, pathParameters, sandboxPath, mode, provider, namespace, repository, ref } = navigationState;
+  return {
+    name: routingRule?.name,
+    params: pathParameters ?? {},
+    sandboxPath,
+    mode,
+    provider,
+    namespace,
+    repository,
+    ref
+  };
 };
 const navigate = (target) => {
   console.log(`[Sandbox] Navigating to ${target}`);
@@ -79,6 +97,9 @@ const navigate = (target) => {
   Router,
   applyRoutingRule,
   navigate,
+  renderRoute,
+  useRoute,
+  useRouteParams,
   useTinkerableLink
 });
 //# sourceMappingURL=routing.cjs.map

package/dist/routing.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/routing.tsx"],"sourcesContent":["import { use, useContext } from 'react';\n\nimport { sendMessage } from './sandboxUtils';\nimport { NavigationState, TinkerableContext } from './TinkerableContext';\nimport { RoutingRule, RoutingSpec } from './RoutingSpec';\nimport { constructUrl, isAbsolutePath, parseTarget } from './urlUtils';\nimport { joinPaths } from './pathUtils';\n\nexport type AppliedRoutingRule = {\n  routingRule: RoutingRule,\n  pathParameters?: Record<string, string>;\n}\n\nexport const useTinkerableLink = (newSandboxLocation: string) => {\n  const { outerHref, navigationState: navigation } = use(TinkerableContext);\n  let newNavigationState = parseTarget(newSandboxLocation, navigation);\n  if (!isAbsolutePath(newSandboxLocation)) {\n    newNavigationState.sandboxPath = joinPaths(navigation.sandboxPath, newSandboxLocation)\n  } else {\n    newNavigationState.sandboxPath = newSandboxLocation\n  }\n  return constructUrl(outerHref, newNavigationState);\n}\n\nexport const applyRoutingRule = (routingSpec:RoutingSpec, navigationState: NavigationState): AppliedRoutingRule | undefined => {\n  const { sandboxPath } = navigationState;\n  for (const routingRule of routingSpec.routes) {\n    if (typeof routingRule.pattern === 'string') {\n      if (routingRule.pattern === sandboxPath) {\n        return {routingRule};\n      }\n    } else {\n      const match = sandboxPath.match(routingRule.pattern);\n      if (routingRule.pattern.test(sandboxPath)) {\n        return {\n          routingRule,\n          pathParameters: match?.groups\n        }\n      }\n    }\n  }\n  return undefined;\n}\n\nexport const Router = () => {\n  const context = useContext(TinkerableContext);\n  const {navigationState: {routingRule}} = context;\n  if (!routingRule) {\n    // TODO: better error\n    throw new Error(`No route registered for path ${context.navigationState.sandboxPath}!`);\n  }\n\n  return routingRule.reactNode;\n};\n\n\n// Perform in-site navigation.\n// Top level frame is messaged to updated URL, after which a message will be\n// sent wit the new href, triggering the actual navigation.\nexport const navigate = (target: string) => {\n  console.log(`[Sandbox] Navigating to ${target}`)\n  sendMessage('urlchange', {\n    url: target,\n    back: false,\n    forward: false,\n  });\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,mBAAgC;AAEhC,0BAA4B;AAC5B,+BAAmD;AAEnD,sBAA0D;AAC1D,uBAA0B;AAOnB,MAAM,oBAAoB,CAAC,uBAA+B;AAC/D,QAAM,EAAE,WAAW,iBAAiB,WAAW,QAAI,kBAAI,0CAAiB;AACxE,MAAI,yBAAqB,6BAAY,oBAAoB,UAAU;AACnE,MAAI,KAAC,gCAAe,kBAAkB,GAAG;AACvC,uBAAmB,kBAAc,4BAAU,WAAW,aAAa,kBAAkB;AAAA,EACvF,OAAO;AACL,uBAAmB,cAAc;AAAA,EACnC;AACA,aAAO,8BAAa,WAAW,kBAAkB;AACnD;AAEO,MAAM,mBAAmB,CAAC,aAAyB,oBAAqE;AAC7H,QAAM,EAAE,YAAY,IAAI;AACxB,aAAW,eAAe,YAAY,QAAQ;AAC5C,QAAI,OAAO,YAAY,YAAY,UAAU;AAC3C,UAAI,YAAY,YAAY,aAAa;AACvC,eAAO,EAAC,YAAW;AAAA,MACrB;AAAA,IACF,OAAO;AACL,YAAM,QAAQ,YAAY,MAAM,YAAY,OAAO;AACnD,UAAI,YAAY,QAAQ,KAAK,WAAW,GAAG;AACzC,eAAO;AAAA,UACL;AAAA,UACA,gBAAgB,OAAO;AAAA,QACzB;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACA,SAAO;AACT;AAEO,MAAM,SAAS,MAAM;AAC1B,QAAM,cAAU,yBAAW,0CAAiB;AAC5C,QAAM,EAAC,iBAAiB,EAAC,YAAW,EAAC,IAAI;AACzC,MAAI,CAAC,aAAa;AAEhB,UAAM,IAAI,MAAM,gCAAgC,QAAQ,gBAAgB,WAAW,GAAG;AAAA,EACxF;AAEA,SAAO,YAAY;AACrB;AAMO,MAAM,WAAW,CAAC,WAAmB;AAC1C,UAAQ,IAAI,2BAA2B,MAAM,EAAE;AAC/C,uCAAY,aAAa;AAAA,IACvB,KAAK;AAAA,IACL,MAAM;AAAA,IACN,SAAS;AAAA,EACX,CAAC;AACH;","names":[]}
+{"version":3,"sources":["../src/routing.tsx"],"sourcesContent":["import type { ReactNode } from 'react';\nimport { use, useContext } from 'react';\n\nimport { sendMessage } from './sandboxUtils';\nimport { NavigationState, TinkerableContext } from './TinkerableContext';\nimport { RouteParams, RoutingRule, RoutingSpec } from './RoutingSpec';\nimport { matchRoute } from './routeMatch';\nimport { constructUrl, isAbsolutePath, parseTarget } from './urlUtils';\nimport { joinPaths } from './pathUtils';\n\n/** The result of matching a path: the winning {@link RoutingRule} plus its captured params. */\nexport type AppliedRoutingRule = {\n  routingRule: RoutingRule,\n  pathParameters?: Record<string, string>;\n}\n\n/** Build the full outer href for an in-app target (absolute `sandboxPath` or a\n *  path relative to the current route), e.g. for an `href` attribute. */\nexport const useTinkerableLink = (newSandboxLocation: string) => {\n  const { outerHref, navigationState: navigation } = use(TinkerableContext);\n  let newNavigationState = parseTarget(newSandboxLocation, navigation);\n  if (!isAbsolutePath(newSandboxLocation)) {\n    newNavigationState.sandboxPath = joinPaths(navigation.sandboxPath, newSandboxLocation)\n  } else {\n    newNavigationState.sandboxPath = newSandboxLocation\n  }\n  return constructUrl(outerHref, newNavigationState);\n}\n\n/** Find the first rule in `routingSpec` whose pattern matches the current\n *  `sandboxPath`, returning it with the captured params (or `undefined`). */\nexport const applyRoutingRule = (routingSpec:RoutingSpec, navigationState: NavigationState): AppliedRoutingRule | undefined => {\n  const { sandboxPath } = navigationState;\n  for (const routingRule of routingSpec.routes) {\n    const pathParameters = matchRoute(routingRule.pattern, sandboxPath);\n    if (pathParameters) {\n      return { routingRule, pathParameters };\n    }\n  }\n  return undefined;\n}\n\n/** Render a matched rule, passing params to a `component` and falling back to `element`/`reactNode`. */\nexport const renderRoute = (routingRule: RoutingRule, params: RouteParams): ReactNode => {\n  if (routingRule.component) {\n    const Component = routingRule.component;\n    return <Component params={params} />;\n  }\n  return routingRule.element ?? routingRule.reactNode ?? null;\n};\n\n/** Render the route matched for the current location (set up by `boot`'s route table). */\nexport const Router = () => {\n  const context = useContext(TinkerableContext);\n  const {navigationState: {routingRule, pathParameters}} = context;\n  if (!routingRule) {\n    // TODO: better error\n    throw new Error(`No route registered for path ${context.navigationState.sandboxPath}!`);\n  }\n\n  return renderRoute(routingRule, pathParameters ?? {});\n};\n\n/** Read the current route's matched params (`:name` segments and the `*` wildcard). */\nexport const useRouteParams = <T extends RouteParams = RouteParams>(): T =>\n  (use(TinkerableContext).navigationState.pathParameters ?? {}) as T;\n\n/**\n * Read the current route: the matched rule's `name`, its `params`, the app-owned\n * `sandboxPath`, and the read-only platform prefix fields (`mode`, `provider`,\n * `namespace`, `repository`, `ref`) — e.g. to tell `/edit` from `/present`.\n */\nexport const useRoute = () => {\n  const { navigationState } = use(TinkerableContext);\n  const { routingRule, pathParameters, sandboxPath, mode, provider, namespace, repository, ref } = navigationState;\n  return {\n    name: routingRule?.name,\n    params: (pathParameters ?? {}) as RouteParams,\n    sandboxPath,\n    mode,\n    provider,\n    namespace,\n    repository,\n    ref,\n  };\n};\n\n\n/**\n * Navigate within the app. Messages the host to update the URL; the host then\n * pushes the new href back, which drives the actual route change.\n */\nexport const navigate = (target: string) => {\n  console.log(`[Sandbox] Navigating to ${target}`)\n  sendMessage('urlchange', {\n    url: target,\n    back: false,\n    forward: false,\n  });\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA8CW;AA7CX,mBAAgC;AAEhC,0BAA4B;AAC5B,+BAAmD;AAEnD,wBAA2B;AAC3B,sBAA0D;AAC1D,uBAA0B;AAUnB,MAAM,oBAAoB,CAAC,uBAA+B;AAC/D,QAAM,EAAE,WAAW,iBAAiB,WAAW,QAAI,kBAAI,0CAAiB;AACxE,MAAI,yBAAqB,6BAAY,oBAAoB,UAAU;AACnE,MAAI,KAAC,gCAAe,kBAAkB,GAAG;AACvC,uBAAmB,kBAAc,4BAAU,WAAW,aAAa,kBAAkB;AAAA,EACvF,OAAO;AACL,uBAAmB,cAAc;AAAA,EACnC;AACA,aAAO,8BAAa,WAAW,kBAAkB;AACnD;AAIO,MAAM,mBAAmB,CAAC,aAAyB,oBAAqE;AAC7H,QAAM,EAAE,YAAY,IAAI;AACxB,aAAW,eAAe,YAAY,QAAQ;AAC5C,UAAM,qBAAiB,8BAAW,YAAY,SAAS,WAAW;AAClE,QAAI,gBAAgB;AAClB,aAAO,EAAE,aAAa,eAAe;AAAA,IACvC;AAAA,EACF;AACA,SAAO;AACT;AAGO,MAAM,cAAc,CAAC,aAA0B,WAAmC;AACvF,MAAI,YAAY,WAAW;AACzB,UAAM,YAAY,YAAY;AAC9B,WAAO,4CAAC,aAAU,QAAgB;AAAA,EACpC;AACA,SAAO,YAAY,WAAW,YAAY,aAAa;AACzD;AAGO,MAAM,SAAS,MAAM;AAC1B,QAAM,cAAU,yBAAW,0CAAiB;AAC5C,QAAM,EAAC,iBAAiB,EAAC,aAAa,eAAc,EAAC,IAAI;AACzD,MAAI,CAAC,aAAa;AAEhB,UAAM,IAAI,MAAM,gCAAgC,QAAQ,gBAAgB,WAAW,GAAG;AAAA,EACxF;AAEA,SAAO,YAAY,aAAa,kBAAkB,CAAC,CAAC;AACtD;AAGO,MAAM,iBAAiB,UAC3B,kBAAI,0CAAiB,EAAE,gBAAgB,kBAAkB,CAAC;AAOtD,MAAM,WAAW,MAAM;AAC5B,QAAM,EAAE,gBAAgB,QAAI,kBAAI,0CAAiB;AACjD,QAAM,EAAE,aAAa,gBAAgB,aAAa,MAAM,UAAU,WAAW,YAAY,IAAI,IAAI;AACjG,SAAO;AAAA,IACL,MAAM,aAAa;AAAA,IACnB,QAAS,kBAAkB,CAAC;AAAA,IAC5B;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF;AACF;AAOO,MAAM,WAAW,CAAC,WAAmB;AAC1C,UAAQ,IAAI,2BAA2B,MAAM,EAAE;AAC/C,uCAAY,aAAa;AAAA,IACvB,KAAK;AAAA,IACL,MAAM;AAAA,IACN,SAAS;AAAA,EACX,CAAC;AACH;","names":[]}

package/dist/routing.d.cts

@@ -1,15 +1,44 @@
-import * as react from 'react';
+import { ReactNode } from 'react';
 import { NavigationState } from './TinkerableContext.cjs';
-import { RoutingRule, RoutingSpec } from './RoutingSpec.cjs';
+import { RoutingRule, RoutingSpec, RouteParams } from './RoutingSpec.cjs';
 import './sandboxTypes.cjs';
 
+/** The result of matching a path: the winning {@link RoutingRule} plus its captured params. */
 type AppliedRoutingRule = {
     routingRule: RoutingRule;
     pathParameters?: Record<string, string>;
 };
+/** Build the full outer href for an in-app target (absolute `sandboxPath` or a
+ *  path relative to the current route), e.g. for an `href` attribute. */
 declare const useTinkerableLink: (newSandboxLocation: string) => string;
+/** Find the first rule in `routingSpec` whose pattern matches the current
+ *  `sandboxPath`, returning it with the captured params (or `undefined`). */
 declare const applyRoutingRule: (routingSpec: RoutingSpec, navigationState: NavigationState) => AppliedRoutingRule | undefined;
-declare const Router: () => react.ReactNode;
+/** Render a matched rule, passing params to a `component` and falling back to `element`/`reactNode`. */
+declare const renderRoute: (routingRule: RoutingRule, params: RouteParams) => ReactNode;
+/** Render the route matched for the current location (set up by `boot`'s route table). */
+declare const Router: () => ReactNode;
+/** Read the current route's matched params (`:name` segments and the `*` wildcard). */
+declare const useRouteParams: <T extends RouteParams = RouteParams>() => T;
+/**
+ * Read the current route: the matched rule's `name`, its `params`, the app-owned
+ * `sandboxPath`, and the read-only platform prefix fields (`mode`, `provider`,
+ * `namespace`, `repository`, `ref`) — e.g. to tell `/edit` from `/present`.
+ */
+declare const useRoute: () => {
+    name: string | undefined;
+    params: RouteParams;
+    sandboxPath: string;
+    mode: string;
+    provider: string;
+    namespace: string;
+    repository: string;
+    ref: string;
+};
+/**
+ * Navigate within the app. Messages the host to update the URL; the host then
+ * pushes the new href back, which drives the actual route change.
+ */
 declare const navigate: (target: string) => void;
 
-export { type AppliedRoutingRule, Router, applyRoutingRule, navigate, useTinkerableLink };
+export { type AppliedRoutingRule, Router, applyRoutingRule, navigate, renderRoute, useRoute, useRouteParams, useTinkerableLink };

package/dist/routing.d.ts

@@ -1,15 +1,44 @@
-import * as react from 'react';
+import { ReactNode } from 'react';
 import { NavigationState } from './TinkerableContext.js';
-import { RoutingRule, RoutingSpec } from './RoutingSpec.js';
+import { RoutingRule, RoutingSpec, RouteParams } from './RoutingSpec.js';
 import './sandboxTypes.js';
 
+/** The result of matching a path: the winning {@link RoutingRule} plus its captured params. */
 type AppliedRoutingRule = {
     routingRule: RoutingRule;
     pathParameters?: Record<string, string>;
 };
+/** Build the full outer href for an in-app target (absolute `sandboxPath` or a
+ *  path relative to the current route), e.g. for an `href` attribute. */
 declare const useTinkerableLink: (newSandboxLocation: string) => string;
+/** Find the first rule in `routingSpec` whose pattern matches the current
+ *  `sandboxPath`, returning it with the captured params (or `undefined`). */
 declare const applyRoutingRule: (routingSpec: RoutingSpec, navigationState: NavigationState) => AppliedRoutingRule | undefined;
-declare const Router: () => react.ReactNode;
+/** Render a matched rule, passing params to a `component` and falling back to `element`/`reactNode`. */
+declare const renderRoute: (routingRule: RoutingRule, params: RouteParams) => ReactNode;
+/** Render the route matched for the current location (set up by `boot`'s route table). */
+declare const Router: () => ReactNode;
+/** Read the current route's matched params (`:name` segments and the `*` wildcard). */
+declare const useRouteParams: <T extends RouteParams = RouteParams>() => T;
+/**
+ * Read the current route: the matched rule's `name`, its `params`, the app-owned
+ * `sandboxPath`, and the read-only platform prefix fields (`mode`, `provider`,
+ * `namespace`, `repository`, `ref`) — e.g. to tell `/edit` from `/present`.
+ */
+declare const useRoute: () => {
+    name: string | undefined;
+    params: RouteParams;
+    sandboxPath: string;
+    mode: string;
+    provider: string;
+    namespace: string;
+    repository: string;
+    ref: string;
+};
+/**
+ * Navigate within the app. Messages the host to update the URL; the host then
+ * pushes the new href back, which drives the actual route change.
+ */
 declare const navigate: (target: string) => void;
 
-export { type AppliedRoutingRule, Router, applyRoutingRule, navigate, useTinkerableLink };
+export { type AppliedRoutingRule, Router, applyRoutingRule, navigate, renderRoute, useRoute, useRouteParams, useTinkerableLink };