@immediately-run/sdk 0.15.0 → 0.16.0

package/dist/runtime.d.cts

@@ -11,6 +11,7 @@ interface SdkHandshake {
     sdkVersion: string;
     protocolVersion: string;
 }
+/** Build this SDK's handshake payload (version + protocol) for the host to record. */
 declare const sdkHandshake: () => SdkHandshake;
 /**
  * Announce this SDK's version to the host (§6). Sends `sdk-handshake` eagerly

package/dist/runtime.d.ts

@@ -11,6 +11,7 @@ interface SdkHandshake {
     sdkVersion: string;
     protocolVersion: string;
 }
+/** Build this SDK's handshake payload (version + protocol) for the host to record. */
 declare const sdkHandshake: () => SdkHandshake;
 /**
  * Announce this SDK's version to the host (§6). Sends `sdk-handshake` eagerly

package/dist/runtime.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/runtime.ts"],"sourcesContent":["// Runtime discovery + version handshake (SDK_PACKAGING_SPEC §4/§6).\n//\n// Today the SDK reaches the host through the INJECTED sandbox services\n// (`module.evaluation.module.bundler.*`, see sandboxUtils). The packaging migration\n// makes the SDK an app-pinnable npm dependency that finds the runtime through a\n// stable, versioned global the sandbox publishes BEFORE evaluating app code:\n//\n//   globalThis.__immediatelyRun__ = { runtimeVersion, protocolVersion, transport }\n//\n// Phase 1 (behind a flag, injection still active): the SDK can READ that global\n// when present (else fall back to injection), and ANNOUNCE its own version +\n// protocol so the host can record + version-check it (§6/T45). The transport itself\n// is unchanged here — this only wires the discovery + handshake fields so the check\n// exists when app-pinned versions become real.\nimport { sendMessage, addListener } from './sandboxUtils';\nimport { SDK_VERSION } from './version';\n\n// `getHostRuntime` + `ImmediatelyRunGlobal` live in the leaf `hostRuntime` module\n// (imports nothing) and are re-exported here for a stable public API. This breaks\n// the sandboxUtils↔runtime import cycle: sandboxUtils reads `getHostRuntime` from\n// the leaf, while runtime still imports sandboxUtils for the handshake — one\n// direction only, no cycle.\nexport { getHostRuntime } from './hostRuntime';\nexport type { ImmediatelyRunGlobal } from './hostRuntime';\n\n/** The wire protocol (postMessage envelope / channels / methods) THIS SDK speaks.\n *  Additive-only (§9); bump only for a backwards-compatible extension. */\nexport const SDK_PROTOCOL_VERSION = '1.0.0';\n\n/** This SDK's package version, baked from package.json at build (SP2-6,\n *  `scripts/gen-version.mjs`). Re-exported so the public surface is unchanged\n *  (`@immediately-run/sdk` → `SDK_VERSION`); imported above for the handshake. */\nexport { SDK_VERSION };\n\n/** This SDK's handshake payload — the version + protocol the host records + checks\n *  against `HOST_PROTOCOL_VERSION` (§6/T45). */\nexport interface SdkHandshake {\n  sdkVersion: string;\n  protocolVersion: string;\n}\nexport const sdkHandshake = (): SdkHandshake => ({\n  sdkVersion: SDK_VERSION,\n  protocolVersion: SDK_PROTOCOL_VERSION,\n});\n\n/**\n * Announce this SDK's version to the host (§6). Sends `sdk-handshake` eagerly\n * (best-effort — the host may already be listening) AND replies to a host\n * `request-handshake` (the robust path, mirroring the other `request-*` pulls).\n * Idempotent; safe to call more than once. Returns an unsubscribe fn.\n */\nexport function announceHandshake(): () => void {\n  const send = () => {\n    try {\n      sendMessage('sdk-handshake', sdkHandshake() as unknown as Record<string, unknown>);\n    } catch {\n      /* transport not ready yet — the request-handshake reply covers it */\n    }\n  };\n  send();\n  return addListener('request-handshake', send);\n}\n"],"mappings":"AAcA,SAAS,aAAa,mBAAmB;AACzC,SAAS,mBAAmB;AAO5B,SAAS,sBAAsB;AAKxB,MAAM,uBAAuB;AAa7B,MAAM,eAAe,OAAqB;AAAA,EAC/C,YAAY;AAAA,EACZ,iBAAiB;AACnB;AAQO,SAAS,oBAAgC;AAC9C,QAAM,OAAO,MAAM;AACjB,QAAI;AACF,kBAAY,iBAAiB,aAAa,CAAuC;AAAA,IACnF,QAAQ;AAAA,IAER;AAAA,EACF;AACA,OAAK;AACL,SAAO,YAAY,qBAAqB,IAAI;AAC9C;","names":[]}
+{"version":3,"sources":["../src/runtime.ts"],"sourcesContent":["// Runtime discovery + version handshake (SDK_PACKAGING_SPEC §4/§6).\n//\n// Today the SDK reaches the host through the INJECTED sandbox services\n// (`module.evaluation.module.bundler.*`, see sandboxUtils). The packaging migration\n// makes the SDK an app-pinnable npm dependency that finds the runtime through a\n// stable, versioned global the sandbox publishes BEFORE evaluating app code:\n//\n//   globalThis.__immediatelyRun__ = { runtimeVersion, protocolVersion, transport }\n//\n// Phase 1 (behind a flag, injection still active): the SDK can READ that global\n// when present (else fall back to injection), and ANNOUNCE its own version +\n// protocol so the host can record + version-check it (§6/T45). The transport itself\n// is unchanged here — this only wires the discovery + handshake fields so the check\n// exists when app-pinned versions become real.\nimport { sendMessage, addListener } from './sandboxUtils';\nimport { SDK_VERSION } from './version';\n\n// `getHostRuntime` + `ImmediatelyRunGlobal` live in the leaf `hostRuntime` module\n// (imports nothing) and are re-exported here for a stable public API. This breaks\n// the sandboxUtils↔runtime import cycle: sandboxUtils reads `getHostRuntime` from\n// the leaf, while runtime still imports sandboxUtils for the handshake — one\n// direction only, no cycle.\nexport { getHostRuntime } from './hostRuntime';\nexport type { ImmediatelyRunGlobal } from './hostRuntime';\n\n/** The wire protocol (postMessage envelope / channels / methods) THIS SDK speaks.\n *  Additive-only (§9); bump only for a backwards-compatible extension. */\nexport const SDK_PROTOCOL_VERSION = '1.0.0';\n\n/** This SDK's package version, baked from package.json at build (SP2-6,\n *  `scripts/gen-version.mjs`). Re-exported so the public surface is unchanged\n *  (`@immediately-run/sdk` → `SDK_VERSION`); imported above for the handshake. */\nexport { SDK_VERSION };\n\n/** This SDK's handshake payload — the version + protocol the host records + checks\n *  against `HOST_PROTOCOL_VERSION` (§6/T45). */\nexport interface SdkHandshake {\n  sdkVersion: string;\n  protocolVersion: string;\n}\n/** Build this SDK's handshake payload (version + protocol) for the host to record. */\nexport const sdkHandshake = (): SdkHandshake => ({\n  sdkVersion: SDK_VERSION,\n  protocolVersion: SDK_PROTOCOL_VERSION,\n});\n\n/**\n * Announce this SDK's version to the host (§6). Sends `sdk-handshake` eagerly\n * (best-effort — the host may already be listening) AND replies to a host\n * `request-handshake` (the robust path, mirroring the other `request-*` pulls).\n * Idempotent; safe to call more than once. Returns an unsubscribe fn.\n */\nexport function announceHandshake(): () => void {\n  const send = () => {\n    try {\n      sendMessage('sdk-handshake', sdkHandshake() as unknown as Record<string, unknown>);\n    } catch {\n      /* transport not ready yet — the request-handshake reply covers it */\n    }\n  };\n  send();\n  return addListener('request-handshake', send);\n}\n"],"mappings":"AAcA,SAAS,aAAa,mBAAmB;AACzC,SAAS,mBAAmB;AAO5B,SAAS,sBAAsB;AAKxB,MAAM,uBAAuB;AAc7B,MAAM,eAAe,OAAqB;AAAA,EAC/C,YAAY;AAAA,EACZ,iBAAiB;AACnB;AAQO,SAAS,oBAAgC;AAC9C,QAAM,OAAO,MAAM;AACjB,QAAI;AACF,kBAAY,iBAAiB,aAAa,CAAuC;AAAA,IACnF,QAAQ;AAAA,IAER;AAAA,EACF;AACA,OAAK;AACL,SAAO,YAAY,qBAAqB,IAAI;AAC9C;","names":[]}

package/dist/sandboxTypes.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/sandboxTypes.ts"],"sourcesContent":["export type ModuleExports = any\n\n// The real type is EvaluationContext from src/bundler/module/Evaluation.ts:6\nexport type EvaluationContext = {\n  exports: ModuleExports;\n  dynamicImport: (moduleToImport: string, symbolToImport:string) => Promise<ModuleExports>;\n  getModuleEvaluationContext: (moduleName: string) =>  Promise<EvaluationContext>;\n  resolve: (moduleName: string) => Promise<string>;\n  evaluation: {\n    module: {\n      source: string;\n      filepath: string;\n    }\n  }\n}\n\nexport type Metadata = Record<string, any>;\nexport type FilesMetadata = Record<string, Metadata>;\nexport type FileQueryResult = string[]\nexport type MetadataQueryFunction = (filesMetadata:FilesMetadata) => FileQueryResult;\nexport type MetadataQueryResult = {result: FileQueryResult} | {error: any}\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../src/sandboxTypes.ts"],"sourcesContent":["/** The exports object of an evaluated sandbox module (untyped — shape depends on the module). */\nexport type ModuleExports = any\n\n/** The sandbox runtime's per-module evaluation context: a module's exports plus the\n *  helpers to dynamically import, resolve, and re-evaluate other modules.\n *  (The real type is `EvaluationContext` from `src/bundler/module/Evaluation.ts`.) */\nexport type EvaluationContext = {\n  exports: ModuleExports;\n  dynamicImport: (moduleToImport: string, symbolToImport:string) => Promise<ModuleExports>;\n  getModuleEvaluationContext: (moduleName: string) =>  Promise<EvaluationContext>;\n  resolve: (moduleName: string) => Promise<string>;\n  evaluation: {\n    module: {\n      source: string;\n      filepath: string;\n    }\n  }\n}\n\n/**\n * The parsed frontmatter of a single file. Apps can supply their own shape as the\n * `T` type parameter on the metadata hooks for typed field access; it defaults to\n * an open record.\n */\nexport type Metadata = Record<string, any>;\n\n/** The whole metadata store: a map from repo-relative file path to its frontmatter. */\nexport type FilesMetadata<T = Metadata> = Record<string, T>;\n\n/** The paths a {@link MetadataQueryFunction} selected. */\nexport type FileQueryResult = string[]\n\n/**\n * A query over the metadata store: receive every file's frontmatter keyed by path\n * and return the paths that match. Plain JS — `Object.entries(...).filter(...)` —\n * no query language to learn.\n */\nexport type MetadataQueryFunction<T = Metadata> = (filesMetadata: FilesMetadata<T>) => FileQueryResult;\n\n/** One match from {@link MetadataQueryFunction}: the file path paired with its frontmatter. */\nexport type MetadataQueryEntry<T = Metadata> = { path: string; meta: T };\n\n/**\n * The result of running a metadata query: the matched entries (path + frontmatter),\n * or the error a throwing query produced.\n */\nexport type MetadataQueryResult<T = Metadata> = MetadataQueryEntry<T>[] | { error: unknown }\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/sandboxTypes.d.cts

@@ -1,4 +1,8 @@
+/** The exports object of an evaluated sandbox module (untyped — shape depends on the module). */
 type ModuleExports = any;
+/** The sandbox runtime's per-module evaluation context: a module's exports plus the
+ *  helpers to dynamically import, resolve, and re-evaluate other modules.
+ *  (The real type is `EvaluationContext` from `src/bundler/module/Evaluation.ts`.) */
 type EvaluationContext = {
     exports: ModuleExports;
     dynamicImport: (moduleToImport: string, symbolToImport: string) => Promise<ModuleExports>;
@@ -11,14 +15,33 @@ type EvaluationContext = {
         };
     };
 };
+/**
+ * The parsed frontmatter of a single file. Apps can supply their own shape as the
+ * `T` type parameter on the metadata hooks for typed field access; it defaults to
+ * an open record.
+ */
 type Metadata = Record<string, any>;
-type FilesMetadata = Record<string, Metadata>;
+/** The whole metadata store: a map from repo-relative file path to its frontmatter. */
+type FilesMetadata<T = Metadata> = Record<string, T>;
+/** The paths a {@link MetadataQueryFunction} selected. */
 type FileQueryResult = string[];
-type MetadataQueryFunction = (filesMetadata: FilesMetadata) => FileQueryResult;
-type MetadataQueryResult = {
-    result: FileQueryResult;
-} | {
-    error: any;
+/**
+ * A query over the metadata store: receive every file's frontmatter keyed by path
+ * and return the paths that match. Plain JS — `Object.entries(...).filter(...)` —
+ * no query language to learn.
+ */
+type MetadataQueryFunction<T = Metadata> = (filesMetadata: FilesMetadata<T>) => FileQueryResult;
+/** One match from {@link MetadataQueryFunction}: the file path paired with its frontmatter. */
+type MetadataQueryEntry<T = Metadata> = {
+    path: string;
+    meta: T;
+};
+/**
+ * The result of running a metadata query: the matched entries (path + frontmatter),
+ * or the error a throwing query produced.
+ */
+type MetadataQueryResult<T = Metadata> = MetadataQueryEntry<T>[] | {
+    error: unknown;
 };
 
-export type { EvaluationContext, FileQueryResult, FilesMetadata, Metadata, MetadataQueryFunction, MetadataQueryResult, ModuleExports };
+export type { EvaluationContext, FileQueryResult, FilesMetadata, Metadata, MetadataQueryEntry, MetadataQueryFunction, MetadataQueryResult, ModuleExports };

package/dist/sandboxTypes.d.ts

@@ -1,4 +1,8 @@
+/** The exports object of an evaluated sandbox module (untyped — shape depends on the module). */
 type ModuleExports = any;
+/** The sandbox runtime's per-module evaluation context: a module's exports plus the
+ *  helpers to dynamically import, resolve, and re-evaluate other modules.
+ *  (The real type is `EvaluationContext` from `src/bundler/module/Evaluation.ts`.) */
 type EvaluationContext = {
     exports: ModuleExports;
     dynamicImport: (moduleToImport: string, symbolToImport: string) => Promise<ModuleExports>;
@@ -11,14 +15,33 @@ type EvaluationContext = {
         };
     };
 };
+/**
+ * The parsed frontmatter of a single file. Apps can supply their own shape as the
+ * `T` type parameter on the metadata hooks for typed field access; it defaults to
+ * an open record.
+ */
 type Metadata = Record<string, any>;
-type FilesMetadata = Record<string, Metadata>;
+/** The whole metadata store: a map from repo-relative file path to its frontmatter. */
+type FilesMetadata<T = Metadata> = Record<string, T>;
+/** The paths a {@link MetadataQueryFunction} selected. */
 type FileQueryResult = string[];
-type MetadataQueryFunction = (filesMetadata: FilesMetadata) => FileQueryResult;
-type MetadataQueryResult = {
-    result: FileQueryResult;
-} | {
-    error: any;
+/**
+ * A query over the metadata store: receive every file's frontmatter keyed by path
+ * and return the paths that match. Plain JS — `Object.entries(...).filter(...)` —
+ * no query language to learn.
+ */
+type MetadataQueryFunction<T = Metadata> = (filesMetadata: FilesMetadata<T>) => FileQueryResult;
+/** One match from {@link MetadataQueryFunction}: the file path paired with its frontmatter. */
+type MetadataQueryEntry<T = Metadata> = {
+    path: string;
+    meta: T;
+};
+/**
+ * The result of running a metadata query: the matched entries (path + frontmatter),
+ * or the error a throwing query produced.
+ */
+type MetadataQueryResult<T = Metadata> = MetadataQueryEntry<T>[] | {
+    error: unknown;
 };
 
-export type { EvaluationContext, FileQueryResult, FilesMetadata, Metadata, MetadataQueryFunction, MetadataQueryResult, ModuleExports };
+export type { EvaluationContext, FileQueryResult, FilesMetadata, Metadata, MetadataQueryEntry, MetadataQueryFunction, MetadataQueryResult, ModuleExports };

package/dist/version.cjs

@@ -21,7 +21,7 @@ __export(version_exports, {
   SDK_VERSION: () => SDK_VERSION
 });
 module.exports = __toCommonJS(version_exports);
-const SDK_VERSION = "0.15.0";
+const SDK_VERSION = "0.16.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   SDK_VERSION

package/dist/version.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/version.ts"],"sourcesContent":["// GENERATED by scripts/gen-version.mjs from package.json — do not edit by hand.\n// Regenerated on every build (prebuild); kept honest by version.test.ts.\n\n/** This SDK's package version, baked from package.json at build (SP2-6). */\nexport const SDK_VERSION = '0.15.0';\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAIO,MAAM,cAAc;","names":[]}
+{"version":3,"sources":["../src/version.ts"],"sourcesContent":["// GENERATED by scripts/gen-version.mjs from package.json — do not edit by hand.\n// Regenerated on every build (prebuild); kept honest by version.test.ts.\n\n/** This SDK's package version, baked from package.json at build (SP2-6). */\nexport const SDK_VERSION = '0.16.0';\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAIO,MAAM,cAAc;","names":[]}

package/dist/version.d.cts

@@ -1,4 +1,4 @@
 /** This SDK's package version, baked from package.json at build (SP2-6). */
-declare const SDK_VERSION = "0.15.0";
+declare const SDK_VERSION = "0.16.0";
 
 export { SDK_VERSION };

package/dist/version.d.ts

@@ -1,4 +1,4 @@
 /** This SDK's package version, baked from package.json at build (SP2-6). */
-declare const SDK_VERSION = "0.15.0";
+declare const SDK_VERSION = "0.16.0";
 
 export { SDK_VERSION };

package/dist/version.js

@@ -1,4 +1,4 @@
-const SDK_VERSION = "0.15.0";
+const SDK_VERSION = "0.16.0";
 export {
   SDK_VERSION
 };

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/version.ts"],"sourcesContent":["// GENERATED by scripts/gen-version.mjs from package.json — do not edit by hand.\n// Regenerated on every build (prebuild); kept honest by version.test.ts.\n\n/** This SDK's package version, baked from package.json at build (SP2-6). */\nexport const SDK_VERSION = '0.15.0';\n"],"mappings":"AAIO,MAAM,cAAc;","names":[]}
+{"version":3,"sources":["../src/version.ts"],"sourcesContent":["// GENERATED by scripts/gen-version.mjs from package.json — do not edit by hand.\n// Regenerated on every build (prebuild); kept honest by version.test.ts.\n\n/** This SDK's package version, baked from package.json at build (SP2-6). */\nexport const SDK_VERSION = '0.16.0';\n"],"mappings":"AAIO,MAAM,cAAc;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@immediately-run/sdk",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Runtime SDK for code executing inside an immediately.run sandbox.",
   "license": "MIT",
   "repository": "github:immediately-run/immediately-run-sdk",
@@ -32,7 +32,7 @@
     "check:circular": "node scripts/check-circular.mjs",
     "api:check": "node scripts/check-api-stability.mjs",
     "api:update": "node scripts/check-api-stability.mjs --update",
-    "docs": "typedoc",
+    "docs": "typedoc --json docs/api.json && node scripts/gen-llms.mjs",
     "prepublishOnly": "npm run check:circular && npm run build && npm run api:check"
   },
   "peerDependencies": {
@@ -43,10 +43,14 @@
     "react-error-boundary": "^6.0.0"
   },
   "devDependencies": {
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
     "@types/jest": "^29.5.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jest": "^29.5.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "jsdom": "^25.0.1",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "ts-jest": "^29.1.0",