@copilotkit/react-native 2.0.0-rc.5 → 2.0.0-rc.51

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.
Files changed (113) hide show
  1. package/README.md +334 -2
  2. package/USAGE.md +382 -21
  3. package/dist/CopilotKitProvider-CBVQLdzn.d.cts +77 -0
  4. package/dist/{CopilotKitProvider-CE4bc6CP.mjs → CopilotKitProvider-CCBBonxr.mjs} +63 -43
  5. package/dist/CopilotKitProvider-CCBBonxr.mjs.map +1 -0
  6. package/dist/CopilotKitProvider-CtQg_0S-.d.mts +77 -0
  7. package/dist/{CopilotKitProvider-Byw3cqe2.cjs → CopilotKitProvider-QdcQrrSA.cjs} +69 -42
  8. package/dist/CopilotKitProvider-QdcQrrSA.cjs.map +1 -0
  9. package/dist/{Markdown-C_9Re36O.cjs → Markdown-DLopAh5W.cjs} +10 -10
  10. package/dist/Markdown-DLopAh5W.cjs.map +1 -0
  11. package/dist/{Markdown-JsYh7oSA.d.mts → Markdown-Du-b_Qpr.d.mts} +3 -3
  12. package/dist/{Markdown-1ips7myr.d.cts → Markdown-UXZdDjzs.d.cts} +3 -3
  13. package/dist/{Markdown-C6AsLHmd.mjs → Markdown-VxtPJ_yh.mjs} +4 -4
  14. package/dist/Markdown-VxtPJ_yh.mjs.map +1 -0
  15. package/dist/{MarkdownRendererContext-CAnuohIS.mjs → MarkdownRendererContext-EobUsERg.mjs} +1 -1
  16. package/dist/{MarkdownRendererContext-CAnuohIS.mjs.map → MarkdownRendererContext-EobUsERg.mjs.map} +1 -1
  17. package/dist/MarkdownRendererContext-cDEHvbw9.cjs +40 -0
  18. package/dist/{MarkdownRendererContext-BRNe808d.cjs.map → MarkdownRendererContext-cDEHvbw9.cjs.map} +1 -1
  19. package/dist/chunk-C0xms8kb.cjs +34 -0
  20. package/dist/components/index.cjs +78 -175
  21. package/dist/components/index.cjs.map +1 -1
  22. package/dist/components/index.d.cts +2 -2
  23. package/dist/components/index.d.mts +2 -2
  24. package/dist/components/index.mjs +76 -174
  25. package/dist/components/index.mjs.map +1 -1
  26. package/dist/generative-ui/index.cjs +612 -0
  27. package/dist/generative-ui/index.cjs.map +1 -0
  28. package/dist/generative-ui/index.d.cts +341 -0
  29. package/dist/generative-ui/index.d.mts +341 -0
  30. package/dist/generative-ui/index.mjs +549 -0
  31. package/dist/generative-ui/index.mjs.map +1 -0
  32. package/dist/headless.cjs +3 -2
  33. package/dist/headless.d.cts +3 -3
  34. package/dist/headless.d.mts +3 -3
  35. package/dist/headless.mjs +2 -2
  36. package/dist/index.cjs +132 -162
  37. package/dist/index.cjs.map +1 -1
  38. package/dist/index.d.cts +37 -19
  39. package/dist/index.d.mts +37 -19
  40. package/dist/index.mjs +131 -162
  41. package/dist/index.mjs.map +1 -1
  42. package/dist/polyfills/encoding.cjs +115 -5
  43. package/dist/polyfills/encoding.cjs.map +1 -1
  44. package/dist/polyfills/encoding.d.cts +31 -1
  45. package/dist/polyfills/encoding.d.mts +31 -1
  46. package/dist/polyfills/encoding.mjs +113 -6
  47. package/dist/polyfills/encoding.mjs.map +1 -1
  48. package/dist/polyfills/streams.cjs +1 -1
  49. package/dist/polyfills.cjs +218 -2
  50. package/dist/polyfills.cjs.map +1 -1
  51. package/dist/polyfills.mjs +217 -1
  52. package/dist/polyfills.mjs.map +1 -1
  53. package/package.json +51 -21
  54. package/project.json +6 -1
  55. package/scripts/__tests__/verify-polyfill-barrel.test.mjs +150 -0
  56. package/scripts/verify-polyfill-barrel.mjs +158 -11
  57. package/src/CopilotChat.tsx +114 -93
  58. package/src/CopilotKitProvider.tsx +101 -130
  59. package/src/CopilotPopup.tsx +2 -2
  60. package/src/CopilotSidebar.tsx +7 -5
  61. package/src/__mocks__/react-native.ts +31 -0
  62. package/src/__mocks__/test-copilotkit.tsx +9 -3
  63. package/src/__tests__/attachments-integration.test.tsx +15 -2
  64. package/src/__tests__/copilot-chat-agentid.test.tsx +15 -2
  65. package/src/__tests__/copilot-chat-attachments.test.tsx +15 -2
  66. package/src/__tests__/copilot-chat-configuration.test.tsx +82 -0
  67. package/src/__tests__/copilot-chat-threads.test.tsx +232 -0
  68. package/src/__tests__/copilot-popup.test.tsx +15 -2
  69. package/src/__tests__/copilot-sidebar.test.tsx +15 -2
  70. package/src/__tests__/copilotkit-alias-exports.test.ts +16 -0
  71. package/src/__tests__/copilotkit-provider.test.tsx +68 -73
  72. package/src/__tests__/generative-ui-harness.tsx +243 -0
  73. package/src/__tests__/generative-ui-provider-props.test-d.tsx +106 -0
  74. package/src/__tests__/generative-ui-rn-mock.tsx +54 -0
  75. package/src/__tests__/generative-ui-wiring.test.tsx +720 -0
  76. package/src/__tests__/generative-ui.test.tsx +1000 -0
  77. package/src/__tests__/headless-entry-surface.test.ts +979 -61
  78. package/src/__tests__/headless-integration.test.tsx +11 -1
  79. package/src/__tests__/use-attachments.test.ts +27 -2
  80. package/src/components/CopilotChat.tsx +106 -233
  81. package/src/components/CopilotModal.tsx +1 -1
  82. package/src/components/Markdown.tsx +4 -4
  83. package/src/components/__tests__/CopilotChat-edge-cases.test.tsx +5 -1
  84. package/src/components/__tests__/CopilotChat.test.tsx +12 -4
  85. package/src/components/__tests__/CopilotChatInterrupt.test.tsx +208 -0
  86. package/src/components/__tests__/Markdown.code-alias.test.tsx +1 -1
  87. package/src/components/index.ts +6 -0
  88. package/src/components/messages/AssistantMessage.tsx +3 -3
  89. package/src/components/messages/TypingIndicator.tsx +4 -4
  90. package/src/generative-ui/GenerativeUIActivity.tsx +235 -0
  91. package/src/generative-ui/GenerativeUIProvider.tsx +171 -0
  92. package/src/generative-ui/GenerativeUISurface.tsx +303 -0
  93. package/src/generative-ui/host.tsx +138 -0
  94. package/src/generative-ui/index.ts +93 -0
  95. package/src/generative-ui/internal.ts +55 -0
  96. package/src/headless.ts +4 -0
  97. package/src/hooks/use-attachments.ts +95 -139
  98. package/src/index.ts +10 -4
  99. package/src/polyfills/__tests__/encoding-utf8.test.ts +112 -0
  100. package/src/polyfills/encoding.ts +160 -4
  101. package/src/types.d.ts +0 -13
  102. package/tsdown.config.ts +1 -0
  103. package/dist/CopilotKitProvider-BWjzCdHN.d.mts +0 -121
  104. package/dist/CopilotKitProvider-Btm10msB.d.cts +0 -121
  105. package/dist/CopilotKitProvider-Byw3cqe2.cjs.map +0 -1
  106. package/dist/CopilotKitProvider-CE4bc6CP.mjs.map +0 -1
  107. package/dist/Markdown-C6AsLHmd.mjs.map +0 -1
  108. package/dist/Markdown-C_9Re36O.cjs.map +0 -1
  109. package/dist/MarkdownRendererContext-BRNe808d.cjs +0 -72
  110. package/dist/streaming-fetch-Bm91EsRc.cjs +0 -225
  111. package/dist/streaming-fetch-Bm91EsRc.cjs.map +0 -1
  112. package/dist/streaming-fetch-Dm1oN4f2.mjs +0 -219
  113. package/dist/streaming-fetch-Dm1oN4f2.mjs.map +0 -1
@@ -1,16 +1,29 @@
1
- import { describe, it, expect, beforeAll } from "vitest";
1
+ import { describe, it, expect, beforeAll, vi } from "vitest";
2
2
  import fs from "node:fs";
3
3
  import path from "node:path";
4
+ import { createRequire } from "node:module";
4
5
  // Type-only, so it is erased and does NOT statically pull the entry this file
5
6
  // deliberately loads at runtime (and is not part of the walked graph either —
6
- // the walk starts at src/headless.ts / src/index.ts, not at this test).
7
+ // the walks start at the package's published entries, ENTRIES and
8
+ // generativeUIEntry below, never at this test).
7
9
  import type * as HeadlessEntry from "../headless";
8
10
  // Same reason, and additionally: the identity assertion below needs the module
9
11
  // this entry re-exports FROM, to compare bindings rather than merely count them.
10
12
  import type * as CoreHeadlessEntry from "@copilotkit/react-core/headless";
11
13
 
12
14
  /**
13
- * Guards the `@copilotkit/react-native/headless` entry (src/headless.ts).
15
+ * Guards the import graphs of the published entries of
16
+ * `@copilotkit/react-native`, with `/headless` (src/headless.ts) as the strict
17
+ * case. ENTRIES is derived from package.json `exports`, so the default barrel,
18
+ * `/components` and the polyfill subpaths are walked as well.
19
+ *
20
+ * The second `describe` covers the opt-in `/generative-ui` entry
21
+ * (src/generative-ui/index.ts): it may reach react-core only through `/context`
22
+ * and the DOM-free `/generative-ui/native`, it may reach the `zod` optional
23
+ * peer, it owns no registry, and no OTHER entry may reach it or any
24
+ * generative-UI subpath of a workspace package (that deny-list is derived from
25
+ * the packages' `exports` maps). The third `describe` checks react-core's built
26
+ * dist for a second copy of a generative UI context module.
14
27
  *
15
28
  * The whole point of the headless entry is that a consumer using only the
16
29
  * provider + agent/tool hooks does NOT have to install (or Metro-stub) the
@@ -26,7 +39,7 @@ import type * as CoreHeadlessEntry from "@copilotkit/react-core/headless";
26
39
  *
27
40
  * ─── Why the walker looks the way it does ──────────────────────────────────
28
41
  * A guard that under-reports is worse than no guard, because it is trusted. The
29
- * first version of this file had four blind spots, each of which let a REAL
42
+ * first version of this file had five blind spots, each of which let a REAL
30
43
  * violation through (or flagged a non-violation), so the walker below is written
31
44
  * to close them and each is covered by a test:
32
45
  *
@@ -93,7 +106,7 @@ const CORE_HEADLESS = "@copilotkit/react-core/headless";
93
106
  // grammars + themes), plus mermaid, cytoscape and katex. Metro does not
94
107
  // tree-shake, so ONE import of that specifier from anywhere in this package puts
95
108
  // all of it in every consumer's app bundle (issue #4893). PR #5883 moved the lean
96
- // hooks into /v2/headless precisely so this package never needs the fat entry.
109
+ // hooks into /headless precisely so this package never needs the fat entry.
97
110
  const ALLOWED_REACT_CORE_ENTRIES = [
98
111
  CORE_HEADLESS,
99
112
  "@copilotkit/react-core/context",
@@ -140,21 +153,6 @@ const FORBIDDEN_REGISTRY_APIS: readonly (readonly [
140
153
  ],
141
154
  ];
142
155
 
143
- // Deliberate exemptions from FORBIDDEN_REGISTRY_APIS: one file, one identifier,
144
- // and the reason it is not a tool/renderer registry. File paths are relative to
145
- // src/ and use forward slashes.
146
- const REGISTRY_API_EXEMPTIONS: readonly (readonly [
147
- file: string,
148
- identifier: string,
149
- why: string,
150
- ])[] = [
151
- [
152
- "components/MarkdownRendererContext.tsx",
153
- "createContext",
154
- "holds the provider-level `markdownRenderer` (a component, or config for the built-in markdown renderer). It stores no tools and no tool-call renderers",
155
- ],
156
- ];
157
-
158
156
  // Heavy modules that must never appear as a direct import from this package.
159
157
  // (Transitive leakage through react-core's own entry is covered separately by
160
158
  // packages/react-core/scripts/assert-headless-purity.mjs — this walker cannot
@@ -165,11 +163,104 @@ const FORBIDDEN_HEAVY = [
165
163
  "cytoscape",
166
164
  "katex",
167
165
  "streamdown",
168
- "@copilotkit/a2ui-renderer",
169
166
  "@copilotkit/web-inspector",
170
167
  "@copilotkit/runtime-client-gql",
171
168
  ];
172
169
 
170
+ /**
171
+ * Deliberate exceptions to FORBIDDEN_REGISTRY_APIS. Each one removes exactly
172
+ * the declaration it names from that one file before the scan, so a second
173
+ * context (or any other registry API) in the same file still trips the ban.
174
+ *
175
+ * `file` is POSIX-style relative to src/, and is compared after normalising
176
+ * `path.relative`'s separators (which are `\` on Windows).
177
+ *
178
+ * Every declaration must match exactly once in the file it names. One that no
179
+ * longer matches (the declaration was reformatted, renamed or removed, or the
180
+ * file moved) is reported as a STALE exemption, naming the exemption and its
181
+ * reason, rather than doing nothing and leaving the identifier ban to blame
182
+ * `createContext` for what is really an out-of-date exemption.
183
+ */
184
+ interface RegistryApiExemption {
185
+ file: string;
186
+ /** Each is replaced by its group 1 (what to keep), once. */
187
+ declarations: RegExp[];
188
+ reason: string;
189
+ }
190
+
191
+ const REGISTRY_API_EXEMPTIONS: readonly RegistryApiExemption[] = [
192
+ {
193
+ file: "components/MarkdownRendererContext.tsx",
194
+ declarations: [
195
+ /(import React, \{ )createContext, /,
196
+ /(const Ctx = )createContext<MarkdownRendererValue \| undefined>\(undefined\);/,
197
+ ],
198
+ reason:
199
+ "holds the provider-level `markdownRenderer` (a component, or config for the built-in markdown renderer). It stores no tools and no tool-call renderers",
200
+ },
201
+ {
202
+ file: "generative-ui/GenerativeUIProvider.tsx",
203
+ declarations: [
204
+ /(import React, \{ )createContext, /,
205
+ /()export const GenerativeUIProviderPresentContext = createContext\(false\);/,
206
+ ],
207
+ reason:
208
+ "a boolean that tells the components below 'no provider' from 'a provider without ui'; it holds no tools or renderers",
209
+ },
210
+ ];
211
+
212
+ /** A path relative to src/, with `/` separators on every platform. */
213
+ const srcRelative = (file: string) =>
214
+ path.relative(srcDir, file).replace(/\\/g, "/");
215
+
216
+ /** How many times `re` matches `code`, ignoring its own `g` flag. */
217
+ const countMatches = (code: string, re: RegExp) =>
218
+ [...code.matchAll(new RegExp(re.source, re.flags.replace("g", "") + "g"))]
219
+ .length;
220
+
221
+ /**
222
+ * Every use of a FORBIDDEN_REGISTRY_APIS identifier in the given modules, as
223
+ * `file: identifier — why`, plus every stale exemption among the files given.
224
+ * Comments are stripped first: the modules name these APIs in prose to explain
225
+ * why they do NOT call them, and a raw text match would fail on the
226
+ * documentation.
227
+ */
228
+ function registryOffenders(
229
+ files: Iterable<string>,
230
+ exemptions: readonly RegistryApiExemption[] = REGISTRY_API_EXEMPTIONS,
231
+ ): string[] {
232
+ const offenders: string[] = [];
233
+ for (const file of files) {
234
+ const here = srcRelative(file);
235
+ let code = stripComments(fs.readFileSync(file, "utf8"));
236
+ const applied = exemptions.filter((e) => e.file === here);
237
+ for (const exemption of applied) {
238
+ for (const declaration of exemption.declarations) {
239
+ const matches = countMatches(code, declaration);
240
+ if (matches !== 1) {
241
+ offenders.push(
242
+ `${here}: stale exemption — ${declaration} matched ${matches} ` +
243
+ `time(s), not once. Update or remove the exemption for ` +
244
+ `"${exemption.reason}"`,
245
+ );
246
+ }
247
+ code = code.replace(declaration, "$1");
248
+ }
249
+ }
250
+ for (const [identifier, why] of FORBIDDEN_REGISTRY_APIS) {
251
+ if (new RegExp(`\\b${identifier}\\b`).test(code)) {
252
+ const exempted = applied.length
253
+ ? ` (this file's exemption, "${applied
254
+ .map((e) => e.reason)
255
+ .join("; ")}", does not cover this use)`
256
+ : "";
257
+ offenders.push(`${here}: ${identifier} — ${why}${exempted}`);
258
+ }
259
+ }
260
+ }
261
+ return offenders;
262
+ }
263
+
173
264
  const indexEntry = path.join(srcDir, "index.ts");
174
265
  const pkgJsonPath = path.resolve(srcDir, "..", "package.json");
175
266
 
@@ -202,9 +293,22 @@ interface PkgManifest {
202
293
  * allow-list, and it is READ from package.json rather than hand-copied so it
203
294
  * cannot drift from the manifest it is meant to describe. Anything else in the
204
295
  * graph is a package the consumer may not have: every optional peer
205
- * (`@gorhom/bottom-sheet`, `expo-*`, `react-native-streamdown`, `zod`), any
206
- * brand-new third-party edge, and any Node builtin (which RN has no business
207
- * reaching). This package's OWN name is deliberately absent, which is what keeps
296
+ * (`@gorhom/bottom-sheet`, `expo-document-picker`, `expo-file-system`,
297
+ * `react-native-gesture-handler`, `react-native-reanimated`,
298
+ * `react-native-streamdown`, `zod`), any brand-new third-party edge, and any
299
+ * Node builtin (which RN has no business reaching).
300
+ *
301
+ * The walk covers this package's OWN sources only, so this set bounds what
302
+ * THEY import, not what the consumer must install in total. `zod` is the case
303
+ * in point: it is an optional peer here, and no module of this package imports
304
+ * it, yet every entry needs it at runtime — react-core's `/headless`, which
305
+ * both entries import, loads `zod` on import, and react-core declares it as a
306
+ * REQUIRED peer (`>=3.25`). It stays an optional peer at `>=3.0.0` here only
307
+ * because making a peer required, or narrowing its range, is a breaking change
308
+ * under scripts/release/lib/breaking-change-gate.ts; react-core's own peer is
309
+ * what makes the consumer install it, at `>=3.25`.
310
+ *
311
+ * This package's OWN name is deliberately absent, which is what keeps
208
312
  * this test doubling as the comment-stripping regression: the eight phantom
209
313
  * `@copilotkit/react-native…` specifiers that JSDoc examples used to harvest are
210
314
  * all self-references, so if `stripComments` regresses they fail here.
@@ -240,6 +344,14 @@ function packageNameOf(spec: string): string {
240
344
  return spec.startsWith("@") ? parts.slice(0, 2).join("/") : parts[0]!;
241
345
  }
242
346
 
347
+ /**
348
+ * `@copilotkit/react-core` or one of its subpaths — by package name, not by
349
+ * prefix, so a sibling package such as `@copilotkit/react-core-foo` is not
350
+ * mistaken for an entry of react-core.
351
+ */
352
+ const isReactCoreSpec = (spec: string) =>
353
+ packageNameOf(spec) === "@copilotkit/react-core";
354
+
243
355
  /**
244
356
  * Comment / string / template alternation, scanned left-to-right in ONE pass.
245
357
  *
@@ -412,12 +524,137 @@ function graphFor(entry: string): Graph {
412
524
  const rel = (files: Iterable<string>) =>
413
525
  [...files].map((f) => path.relative(srcDir, f)).sort();
414
526
 
415
- const ENTRIES: [label: string, entry: string][] = [
416
- ["headless", headlessEntry],
417
- ["default barrel", indexEntry],
527
+ interface ExportingManifest extends PkgManifest {
528
+ name?: string;
529
+ exports?: unknown;
530
+ }
531
+
532
+ const readManifest = (file: string) =>
533
+ JSON.parse(fs.readFileSync(file, "utf8")) as ExportingManifest;
534
+
535
+ /**
536
+ * The file an export resolves to for `import` (else `require`, else
537
+ * `default`), following nested condition objects; null for anything else.
538
+ */
539
+ function exportTarget(value: unknown): string | null {
540
+ if (typeof value === "string") return value;
541
+ if (value && typeof value === "object") {
542
+ for (const condition of ["import", "require", "default"]) {
543
+ const target = exportTarget(
544
+ (value as Record<string, unknown>)[condition],
545
+ );
546
+ if (target) return target;
547
+ }
548
+ }
549
+ return null;
550
+ }
551
+
552
+ /** `./dist/a/b.mjs` -> the `src/a/b.ts(x)` tsdown built it from, if any. */
553
+ function sourceOfDistTarget(target: string): string | null {
554
+ const m = /^\.\/dist\/(.+)\.(?:mjs|cjs|js)$/.exec(target);
555
+ if (!m) return null;
556
+ const base = path.join(srcDir, ...m[1]!.split("/"));
557
+ return [`${base}.ts`, `${base}.tsx`].find((c) => fs.existsSync(c)) ?? null;
558
+ }
559
+
560
+ /** An export subpath, or bare specifier, with a `generative-ui` segment. */
561
+ const hasGenerativeUISegment = (subpath: string) =>
562
+ subpath.split("/").includes("generative-ui");
563
+
564
+ /** Export keys of this package that carry no module to walk, and why. */
565
+ const NON_CODE_EXPORTS: Record<string, string> = {
566
+ "./package.json": "the manifest itself",
567
+ };
568
+
569
+ /**
570
+ * The entries to walk, DERIVED from this package's `exports` map rather than
571
+ * typed in: a hand-written list missed the published `/components` entry, so
572
+ * none of the per-entry bans below applied to it. Every code export lands in
573
+ * exactly one place — `entries` (all the bans below), or `generativeUI` (the
574
+ * opt-in entry, walked by its own `describe`) — and anything that cannot be
575
+ * mapped back to a source module is a `problem`, which a test fails on.
576
+ *
577
+ * Runs at collection time, so it must not throw (blind spot #4 above):
578
+ * failures are collected, not raised.
579
+ */
580
+ function deriveEntries(): {
581
+ entries: [label: string, entry: string][];
582
+ generativeUI: string[];
583
+ problems: string[];
584
+ } {
585
+ const entries: [string, string][] = [];
586
+ const generativeUI: string[] = [];
587
+ const problems: string[] = [];
588
+ try {
589
+ const exportsMap = readManifest(pkgJsonPath).exports;
590
+ if (!exportsMap || typeof exportsMap !== "object") {
591
+ return { entries, generativeUI, problems: ["no `exports` map"] };
592
+ }
593
+ for (const [key, value] of Object.entries(exportsMap)) {
594
+ if (key in NON_CODE_EXPORTS) continue;
595
+ const target = exportTarget(value);
596
+ const source = target ? sourceOfDistTarget(target) : null;
597
+ if (!source) {
598
+ problems.push(
599
+ `${key} -> ${target ?? JSON.stringify(value)}: no src/ module found ` +
600
+ `for it. Teach sourceOfDistTarget the new layout, or add the key ` +
601
+ `to NON_CODE_EXPORTS with a reason.`,
602
+ );
603
+ } else if (hasGenerativeUISegment(key)) {
604
+ generativeUI.push(source);
605
+ } else {
606
+ entries.push([`@copilotkit/react-native${key.slice(1)}`, source]);
607
+ }
608
+ }
609
+ } catch (err) {
610
+ problems.push(`could not read the exports of ${pkgJsonPath}: ${err}`);
611
+ }
612
+ return { entries, generativeUI, problems };
613
+ }
614
+
615
+ const DERIVED_ENTRIES = deriveEntries();
616
+
617
+ // Never empty at collection, so the it.each tables below always register: if
618
+ // the derivation broke, they fall back to the two entries this guard was first
619
+ // written for, and the derivation test reports why.
620
+ const ENTRIES: [label: string, entry: string][] = DERIVED_ENTRIES.entries.length
621
+ ? DERIVED_ENTRIES.entries
622
+ : [
623
+ ["@copilotkit/react-native/headless", headlessEntry],
624
+ ["@copilotkit/react-native", indexEntry],
625
+ ];
626
+
627
+ /** Entries the derivation must find. A floor, not the list. */
628
+ const REQUIRED_ENTRIES = [
629
+ headlessEntry,
630
+ indexEntry,
631
+ path.join(srcDir, "components", "index.ts"),
418
632
  ];
419
633
 
420
634
  describe("@copilotkit/react-native/headless entry", () => {
635
+ it("walks every code export of package.json", () => {
636
+ expect(
637
+ DERIVED_ENTRIES.problems,
638
+ `package.json exports that this guard cannot map to an entry module:\n ` +
639
+ DERIVED_ENTRIES.problems.join("\n "),
640
+ ).toEqual([]);
641
+ const walked = ENTRIES.map(([, entry]) => entry);
642
+ const missing = REQUIRED_ENTRIES.filter((e) => !walked.includes(e));
643
+ expect(
644
+ missing,
645
+ `the entries derived from package.json exports do not include ` +
646
+ `${rel(missing).join(", ")} — the derivation is broken. Derived: ` +
647
+ `${rel(walked).join(", ")}`,
648
+ ).toEqual([]);
649
+ // The opt-in entry is walked by its own describe below, against the path
650
+ // it hard-codes; make sure that path is the one package.json publishes.
651
+ expect(
652
+ DERIVED_ENTRIES.generativeUI,
653
+ "package.json's generative-ui export(s) do not resolve to the entry the " +
654
+ "generative UI describe walks",
655
+ ).toEqual([path.join(srcDir, "generative-ui", "index.ts")]);
656
+ });
657
+
421
658
  // Runs for real now: nothing walks the graph before collection finishes, so a
422
659
  // missing entry file reports HERE instead of erroring the whole suite out.
423
660
  it.each(ENTRIES)("has a %s entry file", (_label, entry) => {
@@ -530,26 +767,7 @@ describe("@copilotkit/react-native/headless entry", () => {
530
767
  const { seen } = graphFor(headlessEntry);
531
768
  // Non-vacuity comes from REQUIRED_HEADLESS_MODULES above (a truncated walk
532
769
  // fails there first), so this only has to be a deny-list.
533
- const offenders: string[] = [];
534
- for (const file of seen) {
535
- // Comments stripped: this file's own graph is heavily documented and the
536
- // modules in it name these APIs in prose to explain why they do NOT call
537
- // them. A raw text match would fail on the documentation.
538
- const code = stripComments(fs.readFileSync(file, "utf8"));
539
- const relFile = path.relative(srcDir, file).split(path.sep).join("/");
540
- for (const [identifier, why] of FORBIDDEN_REGISTRY_APIS) {
541
- const exempt = REGISTRY_API_EXEMPTIONS.some(
542
- ([exemptFile, exemptIdentifier]) =>
543
- exemptFile === relFile && exemptIdentifier === identifier,
544
- );
545
- if (exempt) continue;
546
- if (new RegExp(`\\b${identifier}\\b`).test(code)) {
547
- offenders.push(
548
- `${path.relative(srcDir, file)}: ${identifier} — ${why}`,
549
- );
550
- }
551
- }
552
- }
770
+ const offenders = registryOffenders(seen);
553
771
  expect(
554
772
  offenders,
555
773
  `module(s) in the headless graph touch registry internals directly:\n ` +
@@ -560,11 +778,11 @@ describe("@copilotkit/react-native/headless entry", () => {
560
778
  });
561
779
 
562
780
  /**
563
- * The four checks below need the entry EVALUATED, not just read: they assert
781
+ * The six checks below need the entry EVALUATED, not just read: they assert
564
782
  * that the named exports exist as runtime values (a re-export of a name that
565
783
  * no longer exists is a runtime hole a static read cannot see). So the import
566
784
  * stays — but it is paid exactly once, in a hook, rather than being raced by
567
- * four tests against the default per-test budget.
785
+ * six tests against the default per-test budget.
568
786
  *
569
787
  * Why the budget below is what it is. Nothing here is hung or polling — the
570
788
  * cost is a ONE-TIME module-graph load (resolve + transform + evaluate), paid
@@ -573,12 +791,13 @@ describe("@copilotkit/react-native/headless entry", () => {
573
791
  *
574
792
  * - vitest.config.mjs sets `server.deps.inline: [/@copilotkit/]`, so the
575
793
  * workspace dists this entry pulls are transformed rather than loaded
576
- * natively: ~283 KB (core ~218 KB, react-core v2/headless ~55 KB, plus
577
- * v2/context and shared), on top of the 11 RN source modules.
578
- * - Measured on one dev machine: ~0.9–1.8s inside the full 22-file suite
579
- * (n=8), ~0.7–1.1s for this file alone (n=8) — but 4568ms on the run
580
- * straight after a cold `nx build`, i.e. 91% of the 5s budget, and the
581
- * 4 independent agents who hit this hit it as an outright timeout. Bare
794
+ * natively: ~283 KB (core ~218 KB, react-core /headless ~55 KB, plus
795
+ * /context and shared), on top of the 11 RN source modules.
796
+ * - Measured on one dev machine: ~0.9–1.8s inside the full suite as it
797
+ * was then (22 test files; there are more now) (n=8), ~0.7–1.1s for
798
+ * this file alone (n=8) — but 4568ms on the run straight after a cold
799
+ * `nx build`, i.e. 91% of the 5s budget, and the 4 independent
800
+ * agents who hit this hit it as an outright timeout. Bare
582
801
  * Node `import()` of the equivalent prebuilt dist is 461ms, so the spread
583
802
  * is resolve/transform and page-cache-cold I/O, both load-sensitive.
584
803
  *
@@ -587,7 +806,7 @@ describe("@copilotkit/react-native/headless entry", () => {
587
806
  * ~0ms. A genuinely hung import still fails, just not spuriously. Lowering it
588
807
  * re-introduces the flake; lowering the COST would mean not inlining
589
808
  * `@copilotkit/core` for this suite, which is a shared-config change affecting
590
- * all 22 test files rather than something this file can do.
809
+ * every test file in this package rather than something this file can do.
591
810
  */
592
811
  const IMPORT_BUDGET_MS = 60_000;
593
812
 
@@ -600,7 +819,7 @@ describe("@copilotkit/react-native/headless entry", () => {
600
819
  let coreHeadless: typeof CoreHeadlessEntry;
601
820
 
602
821
  beforeAll(async () => {
603
- // Both loads live in the ONE budgeted hook. core's /v2/headless is already
822
+ // Both loads live in the ONE budgeted hook. core's /headless is already
604
823
  // inside this entry's own graph, so importing it here is a module-cache
605
824
  // hit rather than a second traversal.
606
825
  [mod, coreHeadless] = await Promise.all([
@@ -737,13 +956,11 @@ describe("@copilotkit/react-native/headless entry", () => {
737
956
  // Applies to BOTH entries: the fat-entry ban is package-wide, unlike the
738
957
  // native-peer-dep ban above which only constrains the headless entry.
739
958
  it.each(ENTRIES)(
740
- "%s entry imports no react-core entry other than /v2/headless and /v2/context",
959
+ "%s entry imports no react-core entry other than /headless and /context",
741
960
  (_label, entry) => {
742
961
  const { bareSpecs } = graphFor(entry);
743
962
  const offenders = [...bareSpecs].filter(
744
- (s) =>
745
- s.startsWith("@copilotkit/react-core") &&
746
- !ALLOWED_REACT_CORE_ENTRIES.includes(s),
963
+ (s) => isReactCoreSpec(s) && !ALLOWED_REACT_CORE_ENTRIES.includes(s),
747
964
  );
748
965
  expect(
749
966
  offenders,
@@ -764,3 +981,704 @@ describe("@copilotkit/react-native/headless entry", () => {
764
981
  },
765
982
  );
766
983
  });
984
+
985
+ // ─── @copilotkit/react-native/generative-ui ─────────────────────────────────
986
+ // The generative UI entry is opt-in. It may use react-core's DOM-free generative
987
+ // UI entry, and nothing else of react-core but the shared context; and no other
988
+ // entry may reach it, so a consumer that does not use generative UI never
989
+ // bundles the surface engine or the catalog schemas of @copilotkit/shared.
990
+ // (zod is in the bundle of every entry regardless, but for different reasons:
991
+ // the headless and default entries load it through react-core's /headless,
992
+ // and this entry through react-core's /generative-ui/native, whose chat
993
+ // chunk imports it.)
994
+ const generativeUIEntry = path.join(srcDir, "generative-ui", "index.ts");
995
+ const GENERATIVE_UI_REACT_CORE_ENTRIES = [
996
+ "@copilotkit/react-core/context",
997
+ "@copilotkit/react-core/generative-ui/native",
998
+ ];
999
+ const REQUIRED_GENERATIVE_UI_MODULES = [
1000
+ path.join("generative-ui", "index.ts"),
1001
+ path.join("generative-ui", "GenerativeUIProvider.tsx"),
1002
+ path.join("generative-ui", "GenerativeUIActivity.tsx"),
1003
+ path.join("generative-ui", "GenerativeUISurface.tsx"),
1004
+ path.join("generative-ui", "host.tsx"),
1005
+ ];
1006
+
1007
+ /**
1008
+ * Bare specifiers the generative UI graph MUST harvest. The same non-vacuity
1009
+ * floor as REQUIRED_HEADLESS_BARE: the react-core allow-list and the heavy/DOM
1010
+ * deny-lists below are all filters over `bareSpecs`, and every one of them
1011
+ * passes on an empty set. These two are the edges the entry exists for — the
1012
+ * catalog engine, and the host elements it renders into — so a walk that stops
1013
+ * harvesting them is a walk that is no longer checking anything.
1014
+ */
1015
+ const REQUIRED_GENERATIVE_UI_BARE = [
1016
+ "@copilotkit/react-core/generative-ui/native",
1017
+ "react-native",
1018
+ ];
1019
+
1020
+ /**
1021
+ * Optional peers the generative UI entry is DELIBERATELY allowed to reach, on
1022
+ * top of guaranteedPackages(). None today.
1023
+ *
1024
+ * zod needs no entry: it is not a peer of this package. react-core,
1025
+ * `@copilotkit/core` and `@copilotkit/shared` list it in their own
1026
+ * `dependencies`, so the copy they load is theirs and asks the consumer for
1027
+ * nothing.
1028
+ *
1029
+ * Every optional peer stays unsanctioned: the chat/attachment natives
1030
+ * (`@gorhom/bottom-sheet`, `expo-document-picker`, `expo-file-system`) are
1031
+ * things a generative-UI-only consumer has not been told to install. Extend
1032
+ * this list only with a reason.
1033
+ */
1034
+ const GENERATIVE_UI_ALLOWED_OPTIONAL_PEERS: string[] = [];
1035
+
1036
+ /**
1037
+ * Bare specifiers that ARE generative UI, matched exactly or as a subpath
1038
+ * prefix (never by substring, so an unrelated package whose name merely
1039
+ * contains "generative-ui" neither trips nor hides behind the check).
1040
+ *
1041
+ * DERIVED from the `exports` maps of every workspace package (and of every
1042
+ * `@copilotkit/*` dependency of this package, wherever it resolves): each
1043
+ * export subpath with a `generative-ui` segment. The hand-written list it
1044
+ * replaces missed `@copilotkit/shared/generative-ui` — the catalog schemas —
1045
+ * so the headless and default entries could have imported them unnoticed.
1046
+ *
1047
+ * GENERATIVE_UI_BARE_FLOOR is not the list. It is what the derivation must at
1048
+ * least find, so a derivation that silently finds nothing fails a test instead
1049
+ * of turning the ban off; and it is unioned in, so the ban holds meanwhile.
1050
+ */
1051
+ const matchesBare = (spec: string, dep: string) =>
1052
+ spec === dep || spec.startsWith(`${dep}/`);
1053
+
1054
+ const GENERATIVE_UI_BARE_FLOOR = [
1055
+ "@copilotkit/react-native/generative-ui",
1056
+ "@copilotkit/react-core/generative-ui",
1057
+ "@copilotkit/core/generative-ui",
1058
+ "@copilotkit/shared/generative-ui",
1059
+ ];
1060
+
1061
+ const workspacePackagesDir = path.resolve(srcDir, "..", "..");
1062
+
1063
+ /**
1064
+ * name -> `exports` of every package the derivation reads. Collection-time
1065
+ * and must not throw (blind spot #4): failures are collected as problems.
1066
+ */
1067
+ function scanExportsMaps(): {
1068
+ manifests: Map<string, unknown>;
1069
+ problems: string[];
1070
+ } {
1071
+ const manifests = new Map<string, unknown>();
1072
+ const problems: string[] = [];
1073
+ const add = (file: string) => {
1074
+ try {
1075
+ const pkg = readManifest(file);
1076
+ if (pkg.name && !manifests.has(pkg.name))
1077
+ manifests.set(pkg.name, pkg.exports);
1078
+ } catch (err) {
1079
+ problems.push(`could not read ${file}: ${err}`);
1080
+ }
1081
+ };
1082
+ try {
1083
+ for (const dir of fs.readdirSync(workspacePackagesDir)) {
1084
+ const file = path.join(workspacePackagesDir, dir, "package.json");
1085
+ if (fs.existsSync(file)) add(file);
1086
+ }
1087
+ // Belt and braces for a dependency that is not (or no longer) a
1088
+ // workspace package: read the manifest the consumer would resolve.
1089
+ const own = readManifest(pkgJsonPath);
1090
+ const requireHere = createRequire(pkgJsonPath);
1091
+ for (const name of Object.keys({
1092
+ ...own.dependencies,
1093
+ ...own.peerDependencies,
1094
+ })) {
1095
+ if (!name.startsWith("@copilotkit/") || manifests.has(name)) continue;
1096
+ try {
1097
+ add(requireHere.resolve(`${name}/package.json`));
1098
+ } catch (err) {
1099
+ problems.push(`could not resolve ${name}/package.json: ${err}`);
1100
+ }
1101
+ }
1102
+ } catch (err) {
1103
+ problems.push(`could not scan ${workspacePackagesDir}: ${err}`);
1104
+ }
1105
+ return { manifests, problems };
1106
+ }
1107
+
1108
+ /** The derivation: every export subpath with a `generative-ui` segment. */
1109
+ function deriveGenerativeUIBare(manifests: Map<string, unknown>): string[] {
1110
+ const specs: string[] = [];
1111
+ for (const [name, exportsMap] of manifests) {
1112
+ if (!exportsMap || typeof exportsMap !== "object") continue;
1113
+ for (const key of Object.keys(exportsMap)) {
1114
+ if (hasGenerativeUISegment(key)) specs.push(`${name}${key.slice(1)}`);
1115
+ }
1116
+ }
1117
+ return specs.sort();
1118
+ }
1119
+
1120
+ /**
1121
+ * The cross-check, deliberately looser than the derivation: every export
1122
+ * whose subpath OR target mentions "generative-ui" at all (an export renamed
1123
+ * to `./genui` but still pointing at `dist/generative-ui/…`, or a
1124
+ * `./generative-ui-extras` subpath), that the derivation does not cover.
1125
+ */
1126
+ function uncoveredGenerativeUIExports(
1127
+ manifests: Map<string, unknown>,
1128
+ ): string[] {
1129
+ const derived = deriveGenerativeUIBare(manifests);
1130
+ const uncovered: string[] = [];
1131
+ for (const [name, exportsMap] of manifests) {
1132
+ if (!exportsMap || typeof exportsMap !== "object") continue;
1133
+ for (const [key, value] of Object.entries(exportsMap)) {
1134
+ const spec = `${name}${key.slice(1)}`;
1135
+ if (
1136
+ `${key} ${JSON.stringify(value)}`.includes("generative-ui") &&
1137
+ !derived.some((dep) => matchesBare(spec, dep))
1138
+ ) {
1139
+ uncovered.push(spec);
1140
+ }
1141
+ }
1142
+ }
1143
+ return uncovered.sort();
1144
+ }
1145
+
1146
+ const EXPORTS_SCAN = scanExportsMaps();
1147
+
1148
+ const GENERATIVE_UI_BARE = [
1149
+ ...new Set([
1150
+ ...deriveGenerativeUIBare(EXPORTS_SCAN.manifests),
1151
+ ...GENERATIVE_UI_BARE_FLOOR,
1152
+ ]),
1153
+ ].sort();
1154
+
1155
+ describe("@copilotkit/react-native/generative-ui entry", () => {
1156
+ it("has an entry file", () => {
1157
+ expect(
1158
+ fs.existsSync(generativeUIEntry),
1159
+ `missing entry file: ${generativeUIEntry}`,
1160
+ ).toBe(true);
1161
+ });
1162
+
1163
+ it("resolves every relative import and has no unanalyzable loader", () => {
1164
+ const { unresolved, opaque } = graphFor(generativeUIEntry);
1165
+ expect(
1166
+ unresolved,
1167
+ `unresolvable relative imports in the generative UI graph — the walker ` +
1168
+ `cannot see past these, so a forbidden import hidden behind one would ` +
1169
+ `read as clean: ${unresolved.join(", ")}`,
1170
+ ).toEqual([]);
1171
+ expect(
1172
+ opaque,
1173
+ `import()/require() with a non-literal specifier in the generative UI ` +
1174
+ `graph cannot be checked. Make it a literal: ${opaque.join(", ")}`,
1175
+ ).toEqual([]);
1176
+ });
1177
+
1178
+ // The non-vacuity floor for every deny-list in this block.
1179
+ it("reaches the modules and bare imports it must reach", () => {
1180
+ const { seen, bareSpecs } = graphFor(generativeUIEntry);
1181
+ const reached = rel(seen);
1182
+ const missing = REQUIRED_GENERATIVE_UI_MODULES.filter(
1183
+ (m) => !reached.includes(m),
1184
+ );
1185
+ expect(
1186
+ missing,
1187
+ `the walk did not reach ${missing.join(", ")} — the checks below are ` +
1188
+ `then reasoning about a truncated graph. Reached: ${reached.join(", ")}`,
1189
+ ).toEqual([]);
1190
+ const missingBare = REQUIRED_GENERATIVE_UI_BARE.filter(
1191
+ (s) => !bareSpecs.has(s),
1192
+ );
1193
+ expect(
1194
+ missingBare,
1195
+ `no edge to ${missingBare.join(", ")} was harvested from the generative ` +
1196
+ `UI graph — the allow- and deny-lists below would pass on an empty set. ` +
1197
+ `Harvested: ${[...bareSpecs].sort().join(", ")}`,
1198
+ ).toEqual([]);
1199
+ });
1200
+
1201
+ it("draws only on guaranteed packages, plus the optional peers it is allowed", () => {
1202
+ const { seen, bareSpecs } = graphFor(generativeUIEntry);
1203
+ const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, "utf8")) as PkgManifest;
1204
+ // An allowance for a package that is not even a declared optional peer is a
1205
+ // typo or a stale entry, and would quietly sanction nothing (or the wrong
1206
+ // thing); refuse it rather than trust it.
1207
+ const undeclared = GENERATIVE_UI_ALLOWED_OPTIONAL_PEERS.filter(
1208
+ (name) =>
1209
+ !pkg.peerDependencies?.[name] ||
1210
+ !pkg.peerDependenciesMeta?.[name]?.optional,
1211
+ );
1212
+ expect(
1213
+ undeclared,
1214
+ `GENERATIVE_UI_ALLOWED_OPTIONAL_PEERS names package(s) that are not ` +
1215
+ `optional peers in package.json: ${undeclared.join(", ")}`,
1216
+ ).toEqual([]);
1217
+ const allowed = new Set([
1218
+ ...guaranteedPackages(),
1219
+ ...GENERATIVE_UI_ALLOWED_OPTIONAL_PEERS,
1220
+ ]);
1221
+ const unsanctioned = [...bareSpecs]
1222
+ .filter((spec) => !allowed.has(packageNameOf(spec)))
1223
+ .sort();
1224
+ expect(
1225
+ unsanctioned,
1226
+ `the generative UI graph reaches package(s) a consumer of this entry is ` +
1227
+ `not guaranteed or told to have installed: ${unsanctioned.join(", ")}. ` +
1228
+ `Make it a dependency or non-optional peer in package.json, add it to ` +
1229
+ `GENERATIVE_UI_ALLOWED_OPTIONAL_PEERS with a reason, or drop the import. ` +
1230
+ `Graph: ${rel(seen).join(", ")}`,
1231
+ ).toEqual([]);
1232
+ });
1233
+
1234
+ it("imports only react-core's /context and DOM-free /generative-ui/native", () => {
1235
+ const { bareSpecs } = graphFor(generativeUIEntry);
1236
+ const offenders = [...bareSpecs].filter(
1237
+ (s) =>
1238
+ isReactCoreSpec(s) && !GENERATIVE_UI_REACT_CORE_ENTRIES.includes(s),
1239
+ );
1240
+ expect(
1241
+ offenders,
1242
+ `must import only ${GENERATIVE_UI_REACT_CORE_ENTRIES.join(" or ")} — ` +
1243
+ `found: ${offenders.join(", ")}. /generative-ui carries the DOM ` +
1244
+ `standard catalog (react-dom portals, KaTeX, streamdown), and the root entry the ` +
1245
+ `chat render stack (#4893).`,
1246
+ ).toEqual([]);
1247
+ });
1248
+
1249
+ it("pulls in neither the heavy render stack, the DOM, nor the chat/attachment peers", () => {
1250
+ const { bareSpecs, seen } = graphFor(generativeUIEntry);
1251
+ const banned = [...FORBIDDEN_HEAVY, ...FORBIDDEN_BARE, "react-dom"];
1252
+ const leaked = banned.filter((dep) =>
1253
+ [...bareSpecs].some((s) => matchesBare(s, dep)),
1254
+ );
1255
+ expect(
1256
+ leaked,
1257
+ `generative UI graph must not import: ${leaked.join(", ")}`,
1258
+ ).toEqual([]);
1259
+ // Base-name SUBSTRING matching, as in the headless block: a directory that
1260
+ // merely contains a forbidden name does not trip this, and a chat module
1261
+ // moved to another directory does not escape it — but any file whose base
1262
+ // name contains one (a `useCopilotChatState.ts`, say) does trip it.
1263
+ const chatModules = [...seen].filter((f) =>
1264
+ FORBIDDEN_LOCAL.some((name) =>
1265
+ path
1266
+ .basename(f)
1267
+ .replace(/\.tsx?$/, "")
1268
+ .includes(name),
1269
+ ),
1270
+ );
1271
+ expect(
1272
+ chatModules,
1273
+ `generative UI graph must not reach the chat UI / useAttachments ` +
1274
+ `modules: ${rel(chatModules).join(", ")}`,
1275
+ ).toEqual([]);
1276
+ });
1277
+
1278
+ // The same ban as the headless block's. The generative UI provider registers
1279
+ // no tool (CopilotKitRuntime adds `render_ui` on the server), and the
1280
+ // `render_ui` renderer is written into CopilotKitCoreReact by react-core's
1281
+ // `GenerativeUIToolCallRenderer` (chat.tsx, via `setRenderToolCalls`), which
1282
+ // the provider mounts — in react-core, outside this walk. What this pins is
1283
+ // narrower: no RN module grows a registry (or a context to hold one) next to
1284
+ // CopilotKitCoreReact. Non-vacuity comes from REQUIRED_GENERATIVE_UI_MODULES.
1285
+ it("owns no tool/renderer registry of its own anywhere in the generative UI graph", () => {
1286
+ const { seen } = graphFor(generativeUIEntry);
1287
+ const offenders = registryOffenders(seen);
1288
+ expect(
1289
+ offenders,
1290
+ `module(s) in the generative UI graph touch registry internals ` +
1291
+ `directly:\n ${offenders.join("\n ")}\n` +
1292
+ `CopilotKitCoreReact is the single registry and this package must reach ` +
1293
+ `it only through react-core's hooks.`,
1294
+ ).toEqual([]);
1295
+ });
1296
+
1297
+ it("applies the registry exemption when path.relative uses Windows separators", () => {
1298
+ // `path.relative` returns `\\`-separated paths on Windows, which the
1299
+ // POSIX-style exemption path never equalled, so the exemption silently did
1300
+ // not apply there and this graph's legitimate context failed the ban.
1301
+ const { seen } = graphFor(generativeUIEntry);
1302
+ const posixRelative = path.relative;
1303
+ const spy = vi
1304
+ .spyOn(path, "relative")
1305
+ .mockImplementation((from, to) =>
1306
+ posixRelative(from, to).split("/").join("\\"),
1307
+ );
1308
+ try {
1309
+ expect(registryOffenders(seen)).toEqual([]);
1310
+ } finally {
1311
+ spy.mockRestore();
1312
+ }
1313
+ });
1314
+
1315
+ it("has no stale registry exemption", () => {
1316
+ // Inside registryOffenders, a declaration that no longer matches is
1317
+ // already reported — but only for a file the walk reaches. A file that
1318
+ // moved or left the graph would make its exemption dead without a word,
1319
+ // so check reachability here, against every graph this file walks.
1320
+ const walked = new Set([
1321
+ ...graphFor(generativeUIEntry).seen,
1322
+ ...ENTRIES.flatMap(([, entry]) => [...graphFor(entry).seen]),
1323
+ ]);
1324
+ const stale = REGISTRY_API_EXEMPTIONS.filter(
1325
+ (e) => ![...walked].some((f) => srcRelative(f) === e.file),
1326
+ ).map((e) => `${e.file} ("${e.reason}")`);
1327
+ expect(
1328
+ stale,
1329
+ `stale registry exemption(s): the file is not in any walked graph ` +
1330
+ `(moved, renamed or no longer imported). Update or remove: ` +
1331
+ stale.join(", "),
1332
+ ).toEqual([]);
1333
+ const exemptedFiles = [...walked].filter((f) =>
1334
+ REGISTRY_API_EXEMPTIONS.some((e) => e.file === srcRelative(f)),
1335
+ );
1336
+ // Every exempted file is scanned on its own, so a declaration that no
1337
+ // longer matches exactly once is named here as stale, whichever graph it
1338
+ // is in.
1339
+ expect(
1340
+ registryOffenders(exemptedFiles).filter((o) =>
1341
+ o.includes("stale exemption"),
1342
+ ),
1343
+ ).toEqual([]);
1344
+ });
1345
+
1346
+ it("reports an exemption that no longer matches as stale, naming its reason", () => {
1347
+ // Self-test of the mechanism above, against a deliberately stale copy of
1348
+ // the real exemption: the old code applied it as a silent no-op and then
1349
+ // blamed `createContext` for it.
1350
+ const file = path.join(srcDir, "generative-ui", "GenerativeUIProvider.tsx");
1351
+ const exemption = REGISTRY_API_EXEMPTIONS.find(
1352
+ (e) => e.file === "generative-ui/GenerativeUIProvider.tsx",
1353
+ )!;
1354
+ const stale: RegistryApiExemption[] = REGISTRY_API_EXEMPTIONS.map((e) =>
1355
+ e === exemption
1356
+ ? {
1357
+ ...e,
1358
+ declarations: [
1359
+ ...e.declarations,
1360
+ /()createContext<boolean>\(false\);/,
1361
+ ],
1362
+ }
1363
+ : e,
1364
+ );
1365
+ const offenders = registryOffenders([file], stale);
1366
+ expect(offenders).toHaveLength(1);
1367
+ expect(offenders[0]).toContain("stale exemption");
1368
+ expect(offenders[0]).toContain(exemption.reason);
1369
+ });
1370
+
1371
+ it("derives the generative UI deny-list from every generative UI export", () => {
1372
+ expect(
1373
+ EXPORTS_SCAN.problems,
1374
+ `could not read every exports map the deny-list is derived from:\n ` +
1375
+ EXPORTS_SCAN.problems.join("\n "),
1376
+ ).toEqual([]);
1377
+ const derived = deriveGenerativeUIBare(EXPORTS_SCAN.manifests);
1378
+ const missingFloor = GENERATIVE_UI_BARE_FLOOR.filter(
1379
+ (s) => !derived.includes(s),
1380
+ );
1381
+ expect(
1382
+ missingFloor,
1383
+ `the exports-map derivation no longer finds ${missingFloor.join(", ")} — ` +
1384
+ `either the export was renamed or removed (update ` +
1385
+ `GENERATIVE_UI_BARE_FLOOR) or the derivation is broken. Derived: ` +
1386
+ derived.join(", "),
1387
+ ).toEqual([]);
1388
+ const uncovered = uncoveredGenerativeUIExports(EXPORTS_SCAN.manifests);
1389
+ expect(
1390
+ uncovered,
1391
+ `export(s) that mention generative-ui but are not covered by the ` +
1392
+ `derived deny-list: ${uncovered.join(", ")}. Give the export a ` +
1393
+ `\`generative-ui\` path segment, or teach deriveGenerativeUIBare about ` +
1394
+ `it, so the other entries are kept from reaching it.`,
1395
+ ).toEqual([]);
1396
+ });
1397
+
1398
+ it("the cross-check catches a generative UI export the derivation misses", () => {
1399
+ const manifests = new Map<string, unknown>([
1400
+ [
1401
+ "@copilotkit/example",
1402
+ {
1403
+ "./generative-ui": "./dist/generative-ui.mjs",
1404
+ "./genui": { import: "./dist/generative-ui/extra.mjs" },
1405
+ "./generative-ui-extras": "./dist/extras.mjs",
1406
+ "./other": "./dist/other.mjs",
1407
+ },
1408
+ ],
1409
+ ]);
1410
+ expect(deriveGenerativeUIBare(manifests)).toEqual([
1411
+ "@copilotkit/example/generative-ui",
1412
+ ]);
1413
+ expect(uncoveredGenerativeUIExports(manifests)).toEqual([
1414
+ "@copilotkit/example/generative-ui-extras",
1415
+ "@copilotkit/example/genui",
1416
+ ]);
1417
+ });
1418
+
1419
+ it.each(ENTRIES)(
1420
+ "the %s entry does not reach generative UI",
1421
+ (_label, entry) => {
1422
+ const { seen, bareSpecs } = graphFor(entry);
1423
+ const modules = rel(seen).filter((f) =>
1424
+ f.startsWith(`generative-ui${path.sep}`),
1425
+ );
1426
+ expect(
1427
+ modules,
1428
+ `this entry reaches the opt-in generative UI modules: ` +
1429
+ `${modules.join(", ")}. A consumer who never imports ` +
1430
+ `@copilotkit/react-native/generative-ui must not bundle them.`,
1431
+ ).toEqual([]);
1432
+ const specs = [...bareSpecs]
1433
+ .filter((s) => GENERATIVE_UI_BARE.some((dep) => matchesBare(s, dep)))
1434
+ .sort();
1435
+ expect(
1436
+ specs,
1437
+ `this entry imports generative UI: ${specs.join(", ")}. The surface ` +
1438
+ `engine and its catalog schemas belong only behind the opt-in ` +
1439
+ `@copilotkit/react-native/generative-ui entry.`,
1440
+ ).toEqual([]);
1441
+ },
1442
+ );
1443
+ });
1444
+
1445
+ // ─── react-core dist: one copy of each generative UI context ────────────────
1446
+ // The RN generative UI entry works only if the context its provider SETS and
1447
+ // the context its surfaces READ are the same object. GenerativeUIProvider puts
1448
+ // the runtime into react-core's `GenerativeUIRuntimeContext` and the host into
1449
+ // `GenerativeUIHostContext`, both imported from `/generative-ui/native`;
1450
+ // react-core's own hooks and SurfaceView read them from whatever chunk they
1451
+ // were bundled into. react-core's tsdown config keeps `/generative-ui/native`
1452
+ // in the main build precisely so that every entry shares ONE chunk carrying
1453
+ // these modules. If a config change inlined a second copy (native moved to its
1454
+ // own build, a chunking option), every typecheck and source-level test would
1455
+ // stay green — vitest and tsc see one source module — and a surface would
1456
+ // silently never see its runtime. react-core's context-singleton-preflight only
1457
+ // covers src/context.ts, so this checks the generative UI context modules in
1458
+ // the BUILT dist, by the `//#region <src path>` banner tsdown writes for every
1459
+ // inlined module (the same marker that preflight relies on).
1460
+ const reactCoreDir = (() => {
1461
+ try {
1462
+ return path.dirname(
1463
+ createRequire(pkgJsonPath).resolve("@copilotkit/react-core/package.json"),
1464
+ );
1465
+ } catch {
1466
+ return path.join(workspacePackagesDir, "react-core");
1467
+ }
1468
+ })();
1469
+
1470
+ /** Context modules that MUST be bundled exactly once per format. A floor. */
1471
+ const REQUIRED_SINGLE_CONTEXT_MODULES = [
1472
+ "src/generative-ui/runtime-context.ts",
1473
+ "src/generative-ui/host.tsx",
1474
+ ];
1475
+
1476
+ /** Every file under `dir` (recursively) whose name matches `re`. */
1477
+ function filesUnder(dir: string, re: RegExp): string[] {
1478
+ const out: string[] = [];
1479
+ for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
1480
+ const full = path.join(dir, entry.name);
1481
+ if (entry.isDirectory()) {
1482
+ if (entry.name !== "__tests__") out.push(...filesUnder(full, re));
1483
+ } else if (re.test(entry.name)) {
1484
+ out.push(full);
1485
+ }
1486
+ }
1487
+ return out;
1488
+ }
1489
+
1490
+ describe("@copilotkit/react-core dist: one copy of each generative UI context", () => {
1491
+ it("bundles every generative UI context module at most once per format", () => {
1492
+ const distDir = path.join(reactCoreDir, "dist");
1493
+ expect(
1494
+ fs.existsSync(distDir),
1495
+ `${distDir} does not exist — build @copilotkit/react-core first`,
1496
+ ).toBe(true);
1497
+ // Derived from source: every generative UI module that calls
1498
+ // createContext, so a new context module is covered without listing it.
1499
+ const contextModules = filesUnder(
1500
+ path.join(reactCoreDir, "src", "generative-ui"),
1501
+ /\.tsx?$/,
1502
+ )
1503
+ .filter((f) =>
1504
+ /\bcreateContext\s*[<(]/.test(
1505
+ stripComments(fs.readFileSync(f, "utf8")),
1506
+ ),
1507
+ )
1508
+ .map((f) => path.relative(reactCoreDir, f).split(path.sep).join("/"))
1509
+ .sort();
1510
+ const missingFloor = REQUIRED_SINGLE_CONTEXT_MODULES.filter(
1511
+ (m) => !contextModules.includes(m),
1512
+ );
1513
+ expect(
1514
+ missingFloor,
1515
+ `no createContext found in ${missingFloor.join(", ")} — the source scan ` +
1516
+ `is broken or the module moved; update REQUIRED_SINGLE_CONTEXT_MODULES`,
1517
+ ).toEqual([]);
1518
+
1519
+ // UMD bundles are self-contained by design (as in react-core's own
1520
+ // preflight), so only the ESM and CJS module graphs are checked.
1521
+ const bundles = filesUnder(distDir, /\.(?:mjs|cjs)$/).map((f) => ({
1522
+ file: path.relative(distDir, f).split(path.sep).join("/"),
1523
+ code: fs.readFileSync(f, "utf8"),
1524
+ }));
1525
+ const problems: string[] = [];
1526
+ for (const contextModule of contextModules) {
1527
+ const marker = `//#region ${contextModule}\n`;
1528
+ for (const format of ["mjs", "cjs"]) {
1529
+ const carriers = bundles
1530
+ .filter(
1531
+ (b) => b.file.endsWith(`.${format}`) && b.code.includes(marker),
1532
+ )
1533
+ .map((b) => b.file);
1534
+ const required =
1535
+ REQUIRED_SINGLE_CONTEXT_MODULES.includes(contextModule);
1536
+ if (carriers.length > 1 || (required && carriers.length !== 1)) {
1537
+ problems.push(
1538
+ `${contextModule} is in ${carriers.length} .${format} file(s)` +
1539
+ (carriers.length ? `: ${carriers.join(", ")}` : "") +
1540
+ (required && !carriers.length
1541
+ ? " (expected exactly 1 — or tsdown's region banner changed, " +
1542
+ "and this check can no longer see duplicates)"
1543
+ : ""),
1544
+ );
1545
+ }
1546
+ }
1547
+ }
1548
+ expect(
1549
+ problems,
1550
+ `a generative UI context module is bundled more than once in ` +
1551
+ `@copilotkit/react-core's dist, so a provider and the components ` +
1552
+ `below it can hold different context objects:\n ` +
1553
+ problems.join("\n "),
1554
+ ).toEqual([]);
1555
+ });
1556
+ });
1557
+
1558
+ /**
1559
+ * The first module a source file loads at runtime, in source order: type-only
1560
+ * imports and re-exports are erased, so they are skipped. Null if it loads none.
1561
+ */
1562
+ function firstRuntimeSpecifier(code: string): string | null {
1563
+ const stripped = stripComments(code);
1564
+ const patterns = [
1565
+ /\b(import)\s+(type\s+)?[^;"'`]*?\bfrom\s*["'`]([^"'`]+)["'`]/g,
1566
+ /\b(import)\s*()["'`]([^"'`]+)["'`]/g,
1567
+ /\b(export)\s+(type\s+)?[^;"'`]*?\bfrom\s*["'`]([^"'`]+)["'`]/g,
1568
+ ];
1569
+ let first: { index: number; spec: string } | null = null;
1570
+ for (const re of patterns) {
1571
+ for (const m of stripped.matchAll(re)) {
1572
+ if (m[2]) continue;
1573
+ if (!first || m.index! < first.index) {
1574
+ first = { index: m.index!, spec: m[3]! };
1575
+ }
1576
+ }
1577
+ }
1578
+ return first?.spec ?? null;
1579
+ }
1580
+
1581
+ /** `src/polyfills.ts` and the five modules under `src/polyfills/`. */
1582
+ const polyfillsBarrel = path.join(srcDir, "polyfills.ts");
1583
+ const isPolyfillModule = (file: string) =>
1584
+ file === polyfillsBarrel ||
1585
+ path.dirname(file) === path.join(srcDir, "polyfills");
1586
+
1587
+ /**
1588
+ * Every published entry that loads CopilotKit code. The polyfill subpaths are
1589
+ * the polyfills themselves; everything else reaches @copilotkit/core or
1590
+ * @ag-ui/client, which need ReadableStream / TextEncoder / crypto at load time
1591
+ * on Hermes.
1592
+ */
1593
+ const CODE_ENTRIES: [label: string, entry: string][] = [
1594
+ ...ENTRIES.filter(([, entry]) => !isPolyfillModule(entry)),
1595
+ ...DERIVED_ENTRIES.generativeUI.map(
1596
+ (entry) =>
1597
+ ["@copilotkit/react-native/generative-ui", entry] as [string, string],
1598
+ ),
1599
+ ];
1600
+
1601
+ /**
1602
+ * A glob from package.json `sideEffects` -> a RegExp over `./`-relative paths.
1603
+ * Only the two wildcards this package uses: `**` (any depth) and `*`.
1604
+ */
1605
+ const regexLiteral = (part: string) =>
1606
+ part.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
1607
+
1608
+ function sideEffectsGlob(glob: string): RegExp {
1609
+ const body = glob
1610
+ .split("**/")
1611
+ .map((seg) =>
1612
+ seg
1613
+ .split("**")
1614
+ .map((part) => part.split("*").map(regexLiteral).join("[^/]*"))
1615
+ .join(".*"),
1616
+ )
1617
+ .join("(?:.*/)?");
1618
+ return new RegExp(`^${body}$`);
1619
+ }
1620
+
1621
+ describe("every published entry installs the polyfills before CopilotKit loads", () => {
1622
+ it("covers the root, /headless and /generative-ui entries at least", () => {
1623
+ const walked = CODE_ENTRIES.map(([, entry]) => entry);
1624
+ const floor = [
1625
+ indexEntry,
1626
+ headlessEntry,
1627
+ path.join(srcDir, "generative-ui", "index.ts"),
1628
+ ];
1629
+ expect(
1630
+ floor.filter((e) => !walked.includes(e)),
1631
+ `entries missing from the polyfill-order check; derived: ${rel(walked).join(", ")}`,
1632
+ ).toEqual([]);
1633
+ });
1634
+
1635
+ // An app that imports this entry BEFORE any other @copilotkit/react-native
1636
+ // entry must still get the polyfills first: on Hermes, @copilotkit/core and
1637
+ // @ag-ui/client fail at load time without them, with a ReferenceError that
1638
+ // says nothing about import order. Being imported first in the file is what
1639
+ // makes the bundler emit it as the built entry's first statement, which
1640
+ // scripts/verify-polyfill-barrel.mjs then checks in dist/.
1641
+ it.each(CODE_ENTRIES)(
1642
+ "%s imports ./polyfills as its first runtime import",
1643
+ (_label, entry) => {
1644
+ const first = firstRuntimeSpecifier(fs.readFileSync(entry, "utf8"));
1645
+ expect(
1646
+ first ? resolveLocal(entry, first) : null,
1647
+ `${srcRelative(entry)} must start with \`import "${path
1648
+ .relative(path.dirname(entry), polyfillsBarrel)
1649
+ .replace(/\\/g, "/")
1650
+ .replace(/\.ts$/, "")
1651
+ .replace(/^(?!\.)/, "./")}";\` — its first runtime import is ` +
1652
+ `${JSON.stringify(first)}`,
1653
+ ).toBe(polyfillsBarrel);
1654
+ },
1655
+ );
1656
+
1657
+ // A `sideEffects` list that misses an entry tells the consumer's bundler the
1658
+ // bare `import "./polyfills"` in it can be dropped.
1659
+ it.each(CODE_ENTRIES)(
1660
+ "%s is declared in package.json sideEffects, as source and as build output",
1661
+ (label, entry) => {
1662
+ const manifest = JSON.parse(fs.readFileSync(pkgJsonPath, "utf8")) as {
1663
+ sideEffects?: unknown;
1664
+ exports?: Record<string, unknown>;
1665
+ };
1666
+ const globs = Array.isArray(manifest.sideEffects)
1667
+ ? manifest.sideEffects.map((g) => sideEffectsGlob(String(g)))
1668
+ : [];
1669
+ const key = `.${label.slice("@copilotkit/react-native".length)}`;
1670
+ const exported = manifest.exports?.[key] as
1671
+ | Record<string, string>
1672
+ | undefined;
1673
+ const files = [
1674
+ `./${path.relative(path.dirname(pkgJsonPath), entry).replace(/\\/g, "/")}`,
1675
+ ...Object.values(exported ?? {}),
1676
+ ];
1677
+ expect(files.length, `no exports entry for ${key}`).toBeGreaterThan(1);
1678
+ expect(
1679
+ files.filter((file) => !globs.some((re) => re.test(file))),
1680
+ `not matched by any package.json sideEffects glob`,
1681
+ ).toEqual([]);
1682
+ },
1683
+ );
1684
+ });