Copilot · Oct 6, 2026 · Oct 6, 2026 · Oct 6, 2026 · Oct 7, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -92,6 +92,7 @@ GoodWidget/
 - Treat public component names and theme targets as API surface (renaming is a breaking
   change for integrators).
 - Mirror the issue checklist in the PR body.
+- Render `<WidgetVersion version={version} />` (from `@goodwidget/ui`) in every widget; see `docs/widget-author-instructions.md`.
 - Preserve existing code comments when refactoring files unless explicitly asked to remove
   them.
 

diff --git a/docs/widget-author-instructions.md b/docs/widget-author-instructions.md
@@ -298,6 +298,24 @@ inline. It becomes hard to review and hard to theme correctly.
 
 ---
 
+## Widget Version Label
+
+Every widget must show its own version, read from the widget package's `package.json`, as a
+small muted label in the bottom-right corner. Render the shared `WidgetVersion` primitive as the
+last child of the widget's root (inside `GoodWidgetProvider`) so it never overlaps content:
+
+```tsx
+import { WidgetVersion } from '@goodwidget/ui'
+import { version } from '../package.json'
+
+<WidgetVersion version={version} />
+```
+
+The widget's `tsconfig.json` and `tsconfig.build.json` must use `"rootDir": "."` and include
+`package.json` so the import type-checks.
+
+---
+
 ## Review Checklist
 
 Before requesting review:
@@ -310,6 +328,7 @@ Before requesting review:
 - Light and dark states were checked when the component supports both.
 - Mobile width was checked against the design reference.
 - Storybook screenshots were refreshed when visual states changed.
+- The widget renders `<WidgetVersion version={version} />`.
 - Manual visual review was done against Figma/Stitch/reference screenshots.
 
 If a design seems impossible to express through the current system, do not work around it by

diff --git a/packages/ai-credits-widget/src/AiCreditsWidget.tsx b/packages/ai-credits-widget/src/AiCreditsWidget.tsx
@@ -20,6 +20,8 @@ import {
   createToast,
   updateToast,
 } from '@goodwidget/ui'
+import { version } from '../package.json'
+import { WidgetVersion } from '@goodwidget/ui'
 import { needsWalletConnection, useAiCreditsAdapter } from './adapter'
 import { useAiCreditsHistory } from './useAiCreditsHistory'
 import {
@@ -649,6 +651,7 @@ export function AiCreditsWidget({
           showWalletControls={showWalletControls}
         />
         <ToastContainer />
+        <WidgetVersion version={version} />
       </YStack>
     </GoodWidgetProvider>
   )

diff --git a/packages/ai-credits-widget/tsconfig.build.json b/packages/ai-credits-widget/tsconfig.build.json
@@ -2,10 +2,10 @@
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
     "outDir": "dist",
-    "rootDir": "src",
+    "rootDir": ".",
     "paths": {
       "react-native": ["./node_modules/react-native-web"]
     }
   },
-  "include": ["src"]
+  "include": ["src", "package.json"]
 }
diff --git a/packages/ai-credits-widget/tsconfig.json b/packages/ai-credits-widget/tsconfig.json
@@ -2,13 +2,13 @@
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
     "outDir": "dist",
-    "rootDir": "src",
+    "rootDir": ".",
     "paths": {
       "@goodwidget/core": ["../core/src/index.ts"],
       "@goodwidget/core/*": ["../core/src/*"],
       "@goodwidget/ui": ["../ui/src/index.ts"],
       "react-native": ["./node_modules/react-native-web"]
     }
   },
-  "include": ["src"]
+  "include": ["src", "package.json"]
 }
diff --git a/packages/citizen-claim-widget/src/CitizenClaimWidget.tsx b/packages/citizen-claim-widget/src/CitizenClaimWidget.tsx
@@ -20,6 +20,8 @@ import {
   YStack,
   WidgetTabs,
 } from '@goodwidget/ui'
+import { version } from '../package.json'
+import { WidgetVersion } from '@goodwidget/ui'
 import { SupportedChains } from '@goodsdks/citizen-sdk'
 import { getChainDisplayName, useCitizenClaimAdapter } from './adapter'
 import type {
@@ -687,6 +689,7 @@ export function CitizenClaimWidget({
         onClaimError={onClaimError}
         initialTab={initialTab}
       />
+      <WidgetVersion version={version} />
     </GoodWidgetProvider>
   )
 }
diff --git a/packages/citizen-claim-widget/tsconfig.build.json b/packages/citizen-claim-widget/tsconfig.build.json
@@ -2,10 +2,10 @@
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
     "outDir": "dist",
-    "rootDir": "src",
+    "rootDir": ".",
     "paths": {
       "react-native": ["./node_modules/react-native-web"]
     }
   },
-  "include": ["src"]
+  "include": ["src", "package.json"]
 }
diff --git a/packages/citizen-claim-widget/tsconfig.json b/packages/citizen-claim-widget/tsconfig.json
@@ -2,13 +2,13 @@
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
     "outDir": "dist",
-    "rootDir": "src",
+    "rootDir": ".",
     "paths": {
       "@goodwidget/core": ["../core/src/index.ts"],
       "@goodwidget/core/*": ["../core/src/*"],
       "@goodwidget/ui": ["../ui/src/index.ts"],
       "react-native": ["./node_modules/react-native-web"]
     }
   },
-  "include": ["src"]
+  "include": ["src", "package.json"]
 }
diff --git a/packages/claim-widget-theme-demo/src/ClaimWidget.tsx b/packages/claim-widget-theme-demo/src/ClaimWidget.tsx
@@ -19,6 +19,8 @@ import {
   XStack,
   YStack,
 } from '@goodwidget/ui'
+import { version } from '../package.json'
+import { WidgetVersion } from '@goodwidget/ui'
 
 const ClaimCard = createComponent(Card, {
   name: 'ClaimCard',
@@ -261,6 +263,7 @@ export function ClaimWidget({
       defaultTheme={defaultTheme}
     >
       <ClaimInner />
+      <WidgetVersion version={version} />
     </GoodWidgetProvider>
   )
 }
diff --git a/packages/claim-widget-theme-demo/tsconfig.build.json b/packages/claim-widget-theme-demo/tsconfig.build.json
@@ -2,11 +2,11 @@
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
     "outDir": "dist",
-    "rootDir": "src",
+    "rootDir": ".",
     "paths": {
       "@goodwidget/ui": ["../ui/src/index.ts"],
       "react-native": ["./node_modules/react-native-web"]
     }
   },
-  "include": ["src"]
+  "include": ["src", "package.json"]
 }
diff --git a/packages/claim-widget-theme-demo/tsconfig.json b/packages/claim-widget-theme-demo/tsconfig.json
@@ -2,7 +2,7 @@
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
     "outDir": "dist",
-    "rootDir": "src",
+    "rootDir": ".",
     "paths": {
       "@goodwidget/core": ["../core/src/index.ts"],
       "@goodwidget/core/*": ["../core/src/*"],
@@ -11,5 +11,5 @@
       "react-native": ["./node_modules/react-native-web"]
     }
   },
-  "include": ["src"]
+  "include": ["src", "package.json"]
 }
diff --git a/packages/gooddata-widget/src/GoodDataWidget.tsx b/packages/gooddata-widget/src/GoodDataWidget.tsx
@@ -10,7 +10,8 @@
  */
 import React from 'react'
 import { BrowserRouter, Link, Route, Routes, useParams } from 'react-router-dom'
-import { Heading, Text, YStack } from '@goodwidget/ui'
+import { Heading, Text, WidgetVersion, YStack } from '@goodwidget/ui'
+import { version } from '../package.json'
 import { getDashboard, listDashboards } from './dashboards/registry'
 
 const CONTENT_MAX_WIDTH = 1120
@@ -103,6 +104,7 @@ export function GoodDataWidget({ basename }: GoodDataWidgetProps = {}) {
             <Route path="*" element={<UnknownDashboardPage />} />
           </Routes>
         </BrowserRouter>
+        <WidgetVersion version={version} />
       </YStack>
     </YStack>
   )

diff --git a/packages/gooddata-widget/tsconfig.build.json b/packages/gooddata-widget/tsconfig.build.json
@@ -2,10 +2,10 @@
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
     "outDir": "dist",
-    "rootDir": "src",
+    "rootDir": ".",
     "paths": {
       "react-native": ["./node_modules/react-native-web"]
     }
   },
-  "include": ["src"]
+  "include": ["src", "package.json"]
 }
diff --git a/packages/gooddata-widget/tsconfig.json b/packages/gooddata-widget/tsconfig.json
@@ -2,12 +2,12 @@
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
     "outDir": "dist",
-    "rootDir": "src",
+    "rootDir": ".",
     "paths": {
       "@goodwidget/embed": ["../embed/src/index.ts"],
       "@goodwidget/ui": ["../ui/src/index.ts"],
       "react-native": ["./node_modules/react-native-web"]
     }
   },
-  "include": ["src"]
+  "include": ["src", "package.json"]
 }
diff --git a/packages/goodreserve-widget/src/GoodReserveWidget.tsx b/packages/goodreserve-widget/src/GoodReserveWidget.tsx
@@ -1,6 +1,8 @@
 import React, { useEffect, useRef } from 'react'
 import { GoodWidgetProvider } from '@goodwidget/core'
 import { YStack } from '@goodwidget/ui'
+import { version } from '../package.json'
+import { WidgetVersion } from '@goodwidget/ui'
 import type { EIP1193Provider } from '@goodwidget/core'
 import { ReserveSwapView } from './ReserveSwapView'
 import { useGoodReserveAdapter } from './useGoodReserveAdapter'
@@ -75,6 +77,7 @@ export function GoodReserveWidget({
           mockState={mockState}
           preferredChainId={preferredChainId}
         />
+        <WidgetVersion version={version} />
       </YStack>
     </GoodWidgetProvider>
   )

diff --git a/packages/goodreserve-widget/tsconfig.build.json b/packages/goodreserve-widget/tsconfig.build.json
@@ -2,10 +2,10 @@
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
     "outDir": "dist",
-    "rootDir": "src",
+    "rootDir": ".",
     "paths": {
       "react-native": ["./node_modules/react-native-web"]
     }
   },
-  "include": ["src"]
+  "include": ["src", "package.json"]
 }
diff --git a/packages/goodreserve-widget/tsconfig.json b/packages/goodreserve-widget/tsconfig.json
@@ -2,7 +2,7 @@
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
     "outDir": "dist",
-    "rootDir": "src",
+    "rootDir": ".",
     "paths": {
       "@goodwidget/core": ["../core/src/index.ts"],
       "@goodwidget/core/*": ["../core/src/*"],
@@ -11,5 +11,5 @@
       "react-native": ["./node_modules/react-native-web"]
     }
   },
-  "include": ["src"]
+  "include": ["src", "package.json"]
 }
diff --git a/packages/governance-widget/src/GovernanceOnboardingWidget.tsx b/packages/governance-widget/src/GovernanceOnboardingWidget.tsx
@@ -1,5 +1,6 @@
 import { useMemo } from 'react'
-import { PageWizardProvider } from '@goodwidget/ui'
+import { PageWizardProvider, WidgetVersion } from '@goodwidget/ui'
+import { version } from '../package.json'
 import { GovernanceOnboardingFlow } from './onboarding/GovernanceOnboardingFlow'
 import { DEFAULT_FINAL_ACTIONS, DEFAULT_TRANSACTION_STEPS, ONBOARDING_STEPS } from './onboarding/constants'
 import { HOUSE_COPY } from './onboarding/copy'
@@ -63,6 +64,7 @@ export function GovernanceOnboardingWidget({
         onFinalActionPress={onFinalActionPress}
         dataTestId={dataTestId}
       />
+      <WidgetVersion version={version} />
     </PageWizardProvider>
   )
 }
diff --git a/packages/governance-widget/src/GovernanceWidget.tsx b/packages/governance-widget/src/GovernanceWidget.tsx
@@ -12,6 +12,8 @@ import {
   XStack,
   YStack,
 } from '@goodwidget/ui'
+import { version } from '../package.json'
+import { WidgetVersion } from '@goodwidget/ui'
 import { useTheme } from 'tamagui'
 import { AlignmentVotingProposalCard } from './AlignmentVotingProposalCard'
 import { BalanceCard } from './BalanceCard'
@@ -759,6 +761,7 @@ export function GovernanceWidget({
       ) : (
         <DefaultGovernanceWidgetContent adapterInput={adapterInput} testId={testId} />
       )}
+      <WidgetVersion version={version} />
     </GovernanceWidgetProvider>
   )
 }
diff --git a/packages/governance-widget/tsconfig.build.json b/packages/governance-widget/tsconfig.build.json
@@ -2,7 +2,7 @@
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
     "outDir": "dist",
-    "rootDir": "src"
+    "rootDir": "."
   },
-  "include": ["src"]
+  "include": ["src", "package.json"]
 }
diff --git a/packages/governance-widget/tsconfig.json b/packages/governance-widget/tsconfig.json
@@ -2,11 +2,11 @@
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
     "outDir": "dist",
-    "rootDir": "src",
+    "rootDir": ".",
     "paths": {
       "@goodwidget/ui": ["../ui/src/index.ts"],
       "react-native": ["./node_modules/react-native-web"]
     }
   },
-  "include": ["src"]
+  "include": ["src", "package.json"]
 }
diff --git a/packages/staking-migration-widget/src/StakingMigrationWidget.tsx b/packages/staking-migration-widget/src/StakingMigrationWidget.tsx
@@ -2,6 +2,8 @@ import React, { useCallback, useMemo } from 'react'
 import { GoodWidgetProvider } from '@goodwidget/core'
 import type { EIP1193Provider } from '@goodwidget/core'
 import { Text, ToastContainer, YStack } from '@goodwidget/ui'
+import { version } from '../package.json'
+import { WidgetVersion } from '@goodwidget/ui'
 import { MigrationProgressTimeline } from './MigrationProgressTimeline'
 import { MigrationSummaryCard } from './MigrationSummaryCard'
 import { MigrationSecondaryCard } from './migrationWidgetComponents'
@@ -155,6 +157,7 @@ export function StakingMigrationWidget({
         adapterFactory={adapterFactory}
       />
       <ToastContainer />
+      <WidgetVersion version={version} />
     </GoodWidgetProvider>
   )
 }
diff --git a/packages/staking-migration-widget/tsconfig.build.json b/packages/staking-migration-widget/tsconfig.build.json
@@ -2,10 +2,10 @@
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
     "outDir": "dist",
-    "rootDir": "src",
+    "rootDir": ".",
     "paths": {
       "react-native": ["./node_modules/react-native-web"]
     }
   },
-  "include": ["src"]
+  "include": ["src", "package.json"]
 }
diff --git a/packages/staking-migration-widget/tsconfig.json b/packages/staking-migration-widget/tsconfig.json
@@ -2,13 +2,13 @@
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
     "outDir": "dist",
-    "rootDir": "src",
+    "rootDir": ".",
     "paths": {
       "@goodwidget/core": ["../core/src/index.ts"],
       "@goodwidget/core/*": ["../core/src/*"],
       "@goodwidget/ui": ["../ui/src/index.ts"],
       "react-native": ["./node_modules/react-native-web"]
     }
   },
-  "include": ["src"]
+  "include": ["src", "package.json"]
 }
diff --git a/packages/streaming-widget/src/StreamingWidget.tsx b/packages/streaming-widget/src/StreamingWidget.tsx
@@ -2,6 +2,8 @@ import React from 'react'
 import { GoodWidgetProvider } from '@goodwidget/core'
 import type { EIP1193Provider } from '@goodwidget/core'
 import { ToastContainer } from '@goodwidget/ui'
+import { version } from '../package.json'
+import { WidgetVersion } from '@goodwidget/ui'
 import { useStreamingAdapter } from './adapter'
 import { StreamingWidgetView } from './components/StreamingWidgetView'
 import type {
@@ -47,6 +49,7 @@ export function StreamingWidgetPreview({
         initialStreamsFormOpen={initialStreamsFormOpen}
       />
       <ToastContainer />
+      <WidgetVersion version={version} />
     </GoodWidgetProvider>
   )
 }
@@ -68,6 +71,7 @@ export function StreamingWidget({
     >
       <StreamingWidgetRuntime environment={environment} apiKey={apiKey} />
       <ToastContainer />
+      <WidgetVersion version={version} />
     </GoodWidgetProvider>
   )
 }