@powerhousedao/connect 6.2.3-dev.7 → 6.2.3-dev.70

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 (235) hide show
  1. package/CUSTOMIZING.md +80 -0
  2. package/README.md +28 -0
  3. package/RUNTIME-CONFIG.md +472 -0
  4. package/dist/{AddDriveModal-xAw48kdl.js → AddDriveModal-BjgmiHJr.js} +10 -10
  5. package/dist/AddDriveModal-BjgmiHJr.js.map +1 -0
  6. package/dist/{ClearStorageModal-Czo-h6OE.js → ClearStorageModal-BwGVIuLX.js} +11 -13
  7. package/dist/ClearStorageModal-BwGVIuLX.js.map +1 -0
  8. package/dist/{ConfirmDocumentUpgradeModal-FUOhZsk7.js → ConfirmDocumentUpgradeModal-CoixS60F.js} +9 -8
  9. package/dist/ConfirmDocumentUpgradeModal-CoixS60F.js.map +1 -0
  10. package/dist/{CookiesPolicyModal-BpyPPyxS.js → CookiesPolicyModal-BpFjYc7T.js} +5 -5
  11. package/dist/{CookiesPolicyModal-BpyPPyxS.js.map → CookiesPolicyModal-BpFjYc7T.js.map} +1 -1
  12. package/dist/{CreateDocumentModal-C45W8J0V.js → CreateDocumentModal-B-cXzeOA.js} +11 -10
  13. package/dist/CreateDocumentModal-B-cXzeOA.js.map +1 -0
  14. package/dist/{DebugSettingsModal-BUkre5Ke.js → DebugSettingsModal-DfOnR4iY.js} +9 -9
  15. package/dist/DebugSettingsModal-DfOnR4iY.js.map +1 -0
  16. package/dist/{DeleteDriveModal-Dug84t1j.js → DeleteDriveModal-1pAIayG_.js} +7 -7
  17. package/dist/DeleteDriveModal-1pAIayG_.js.map +1 -0
  18. package/dist/{DeleteItemModal-mMzy3V8o.js → DeleteItemModal-BUpqmFxS.js} +8 -8
  19. package/dist/DeleteItemModal-BUpqmFxS.js.map +1 -0
  20. package/dist/{DisclaimerModal-DvpD5dPM.js → DisclaimerModal-TIJXRYLF.js} +7 -7
  21. package/dist/DisclaimerModal-TIJXRYLF.js.map +1 -0
  22. package/dist/{DocumentVersionUnsupportedModal-C3Q0V75l.js → DocumentVersionUnsupportedModal-DH9Zzsyw.js} +6 -6
  23. package/dist/DocumentVersionUnsupportedModal-DH9Zzsyw.js.map +1 -0
  24. package/dist/{DownloadDocumentWithErrorsModal-IKl0ljQb.js → DownloadDocumentWithErrorsModal-Beh-xw8B.js} +8 -7
  25. package/dist/DownloadDocumentWithErrorsModal-Beh-xw8B.js.map +1 -0
  26. package/dist/{DriveAuthRequiredModal-DVK7ZQzO.js → DriveAuthRequiredModal-XTcoJKvj.js} +7 -7
  27. package/dist/DriveAuthRequiredModal-XTcoJKvj.js.map +1 -0
  28. package/dist/{DriveSettingsModal-C6-mRQiv.js → DriveSettingsModal-DZKawN7w.js} +6 -6
  29. package/dist/DriveSettingsModal-DZKawN7w.js.map +1 -0
  30. package/dist/FloatingTanStackRouterDevtools-CqogiFob-dxj8lrTP.js +2565 -0
  31. package/dist/FloatingTanStackRouterDevtools-CqogiFob-dxj8lrTP.js.map +1 -0
  32. package/dist/{InspectorModal-C-dm0iSW.js → InspectorModal-BVqRNFfP.js} +70 -30
  33. package/dist/InspectorModal-BVqRNFfP.js.map +1 -0
  34. package/dist/{LoginModal-CybbOm3N.js → LoginModal-O06ZvWFI.js} +8 -8
  35. package/dist/LoginModal-O06ZvWFI.js.map +1 -0
  36. package/dist/{OpenFileDocumentsModal-DEcFBZ5I.js → OpenFileDocumentsModal-BNHD0vg9.js} +16 -14
  37. package/dist/OpenFileDocumentsModal-BNHD0vg9.js.map +1 -0
  38. package/dist/{UpgradeDriveModal-_8t9slxQ.js → UpgradeDriveModal-CCWKp5yn.js} +7 -7
  39. package/dist/UpgradeDriveModal-CCWKp5yn.js.map +1 -0
  40. package/dist/app-loader-BjAXSJQ6.js +4 -0
  41. package/dist/app-loader-DtH6v5CE.js +1244 -0
  42. package/dist/app-loader-DtH6v5CE.js.map +1 -0
  43. package/dist/app-skeleton-BFjvlTWd.js +112 -0
  44. package/dist/app-skeleton-BFjvlTWd.js.map +1 -0
  45. package/dist/app-skeleton-DFg65Rxa.js +4 -0
  46. package/dist/boot-N7f3RrY_.js +233 -0
  47. package/dist/boot-N7f3RrY_.js.map +1 -0
  48. package/dist/buffer-DNTcuap_.js +66 -0
  49. package/dist/buffer-DNTcuap_.js.map +1 -0
  50. package/dist/{build-info-N6D-34wu.js → build-info-TgBEqTq1.js} +10 -6
  51. package/dist/build-info-TgBEqTq1.js.map +1 -0
  52. package/dist/components-B_wpF5Is.js +121 -0
  53. package/dist/components-B_wpF5Is.js.map +1 -0
  54. package/dist/{connect.config-DaHDEUrw.js → connect.config-D1pGNmaF.js} +25 -13
  55. package/dist/connect.config-D1pGNmaF.js.map +1 -0
  56. package/dist/{connection-state-3w4liC1X.js → connection-state-B6fleM37.js} +20 -9
  57. package/dist/connection-state-B6fleM37.js.map +1 -0
  58. package/dist/context-De2EB1AA-Ni0d829Q.js +1759 -0
  59. package/dist/context-De2EB1AA-Ni0d829Q.js.map +1 -0
  60. package/dist/{cookie-banner-BH6bIq24.js → cookie-banner-CAvd3PC3.js} +7 -7
  61. package/dist/{cookie-banner-BH6bIq24.js.map → cookie-banner-CAvd3PC3.js.map} +1 -1
  62. package/dist/document-editor-container-CGLXOl0t.js +4 -0
  63. package/dist/document-editor-container-FNIEsf8H.js +310 -0
  64. package/dist/document-editor-container-FNIEsf8H.js.map +1 -0
  65. package/dist/drive-icon-BiVP8yJc.js +38 -0
  66. package/dist/drive-icon-BiVP8yJc.js.map +1 -0
  67. package/dist/error-boundary-BsUBww61.js +155 -0
  68. package/dist/error-boundary-BsUBww61.js.map +1 -0
  69. package/dist/esm-BDACZntJ.js +148 -0
  70. package/dist/esm-BDACZntJ.js.map +1 -0
  71. package/dist/generic.d.ts +116 -0
  72. package/dist/generic.d.ts.map +1 -0
  73. package/dist/generic.js +31 -0
  74. package/dist/generic.js.map +1 -0
  75. package/dist/{i18n-CWO0vYVd.js → i18n-D9WYPgk9.js} +4 -4
  76. package/dist/{i18n-CWO0vYVd.js.map → i18n-D9WYPgk9.js.map} +1 -1
  77. package/dist/index-NyJPEHvw.d.ts +4 -0
  78. package/dist/layout-wfvkfP4J.js +5 -0
  79. package/dist/layout.d.ts +3 -0
  80. package/dist/layout.js +4 -0
  81. package/dist/{load-BxUCaDLH.js → load-CkbGF6wB.js} +48 -46
  82. package/dist/load-CkbGF6wB.js.map +1 -0
  83. package/dist/load-runtime-config-DXswYA71.js +14 -0
  84. package/dist/load-runtime-config-DXswYA71.js.map +1 -0
  85. package/dist/main.d.ts +2 -1
  86. package/dist/main.js +8 -8
  87. package/dist/main.js.map +1 -1
  88. package/dist/open-file-uploads-B5pr1sA2.js +183 -0
  89. package/dist/open-file-uploads-B5pr1sA2.js.map +1 -0
  90. package/dist/package-manager-CPqbVSd8.js +524 -0
  91. package/dist/package-manager-CPqbVSd8.js.map +1 -0
  92. package/dist/{pglite-major-B39aOEiE.js → pglite-major-p4_YefAE.js} +23 -5
  93. package/dist/pglite-major-p4_YefAE.js.map +1 -0
  94. package/dist/{pglite-migrate-core-Boxqqx-c.js → pglite-migrate-core-DBlU6HIc.js} +9 -7
  95. package/dist/pglite-migrate-core-DBlU6HIc.js.map +1 -0
  96. package/dist/{pglite-seed-BqAUvNFw.js → pglite-seed-eGzXMld2.js} +4 -4
  97. package/dist/{pglite-seed-BqAUvNFw.js.map → pglite-seed-eGzXMld2.js.map} +1 -1
  98. package/dist/pglite.worker.d.ts +2 -1
  99. package/dist/pglite.worker.js +4 -3
  100. package/dist/pglite.worker.js.map +1 -1
  101. package/dist/pglite.worker.legacy.d.ts +2 -1
  102. package/dist/pglite.worker.legacy.js +4 -3
  103. package/dist/pglite.worker.legacy.js.map +1 -1
  104. package/dist/plugins-CWbr0n_Q.js +246 -0
  105. package/dist/plugins-CWbr0n_Q.js.map +1 -0
  106. package/dist/{preferences-store-_5Cw4_YV.js → preferences-store-CSqauT9V.js} +6 -25
  107. package/dist/preferences-store-CSqauT9V.js.map +1 -0
  108. package/dist/prerender.d.ts +38 -0
  109. package/dist/prerender.d.ts.map +1 -0
  110. package/dist/prerender.js +177 -0
  111. package/dist/prerender.js.map +1 -0
  112. package/dist/prerendered-shell-peKE7AqI.js +51 -0
  113. package/dist/prerendered-shell-peKE7AqI.js.map +1 -0
  114. package/dist/{pwa-manifest-link-DIgOSo2Q.js → pwa-manifest-link-DQRJpF0r.js} +3 -3
  115. package/dist/{pwa-manifest-link-DIgOSo2Q.js.map → pwa-manifest-link-DQRJpF0r.js.map} +1 -1
  116. package/dist/{reactor-Bg0Y9sdl.js → reactor-DLCl-WHi.js} +509 -562
  117. package/dist/reactor-DLCl-WHi.js.map +1 -0
  118. package/dist/reactor-chat-LAB-9G3G.js +50 -0
  119. package/dist/reactor-chat-LAB-9G3G.js.map +1 -0
  120. package/dist/reactor.worker.d.ts +2 -1
  121. package/dist/reactor.worker.js +478 -156
  122. package/dist/reactor.worker.js.map +1 -1
  123. package/dist/{registerServiceWorker-BSzbNfvz.js → registerServiceWorker-APlHkrmH.js} +5 -5
  124. package/dist/{registerServiceWorker-BSzbNfvz.js.map → registerServiceWorker-APlHkrmH.js.map} +1 -1
  125. package/dist/root-B1Pq9x6S.js +24 -0
  126. package/dist/root-B1Pq9x6S.js.map +1 -0
  127. package/dist/route-tree.d.ts +2220 -0
  128. package/dist/route-tree.d.ts.map +1 -0
  129. package/dist/route-tree.js +135 -0
  130. package/dist/route-tree.js.map +1 -0
  131. package/dist/route-views-BF0p-4Fi.js +60 -0
  132. package/dist/route-views-BF0p-4Fi.js.map +1 -0
  133. package/dist/route-views-CTARvT5N.js +55 -0
  134. package/dist/route-views-CTARvT5N.js.map +1 -0
  135. package/dist/route-views-D8I-1PWU.js +4 -0
  136. package/dist/route-views.d.ts +7 -0
  137. package/dist/route-views.d.ts.map +1 -0
  138. package/dist/route-views.js +4 -0
  139. package/dist/router-BguOMBUh.js +4 -0
  140. package/dist/router-L9X9U-97.js +46 -0
  141. package/dist/router-L9X9U-97.js.map +1 -0
  142. package/dist/router.d.ts +2 -0
  143. package/dist/router.js +3 -0
  144. package/dist/sentry-Cuc_Nbba.js +22 -0
  145. package/dist/sentry-Cuc_Nbba.js.map +1 -0
  146. package/dist/settings-B-apZN_f.js +1084 -0
  147. package/dist/settings-B-apZN_f.js.map +1 -0
  148. package/dist/settings-tabs-CRgiuZcb.js +385 -0
  149. package/dist/settings-tabs-CRgiuZcb.js.map +1 -0
  150. package/dist/shell-core-head.html +2 -0
  151. package/dist/shell-core.html +1 -0
  152. package/dist/shell-head.html +2 -0
  153. package/dist/shell-plugins.json +1 -0
  154. package/dist/shell.html +1 -0
  155. package/dist/start-connect.d.ts +7 -9
  156. package/dist/start-connect.d.ts.map +1 -1
  157. package/dist/start-connect.js +9 -8
  158. package/dist/start-connect.js.map +1 -1
  159. package/dist/store-lock-Bi3B9VJD.js +159 -0
  160. package/dist/store-lock-Bi3B9VJD.js.map +1 -0
  161. package/dist/style.css +3131 -774
  162. package/dist/{toast-BXIGd4Eb.js → toast-C6WW-_O-.js} +3 -3
  163. package/dist/{toast-BXIGd4Eb.js.map → toast-C6WW-_O-.js.map} +1 -1
  164. package/dist/ui-CwbE23ra.js +66 -0
  165. package/dist/ui-CwbE23ra.js.map +1 -0
  166. package/dist/{use-renown-login-Cf3va6u_.js → use-renown-login-dPpDOYq5.js} +4 -4
  167. package/dist/use-renown-login-dPpDOYq5.js.map +1 -0
  168. package/docs/customizing/data-and-navigation.md +232 -0
  169. package/docs/customizing/hosts-and-plugins.md +65 -0
  170. package/docs/customizing/layout.md +149 -0
  171. package/docs/customizing/modals.md +78 -0
  172. package/docs/customizing/overrides.md +113 -0
  173. package/docs/customizing/packages.md +39 -0
  174. package/docs/customizing/pages.md +136 -0
  175. package/docs/customizing/styles-and-branding.md +69 -0
  176. package/docs/customizing/types-and-troubleshooting.md +63 -0
  177. package/fonts.css +177 -0
  178. package/package.json +81 -25
  179. package/scripts/prerender-shell.ts +51 -0
  180. package/skills/customize-connect/SKILL.md +74 -0
  181. package/src/route-tree.ts +3 -0
  182. package/src/routeTree.gen.ts +235 -0
  183. package/src/router/index.ts +2 -0
  184. package/src/router/register.ts +9 -0
  185. package/src/routes/__root.tsx +12 -0
  186. package/src/routes/_app/$.tsx +13 -0
  187. package/src/routes/_app/d/$driveSlug/{-$nodeSlug}.tsx +13 -0
  188. package/src/routes/_app/d/$driveSlug.tsx +13 -0
  189. package/src/routes/_app/index.tsx +13 -0
  190. package/src/routes/_app/settings/appearance.tsx +13 -0
  191. package/src/routes/_app/settings/packages.tsx +13 -0
  192. package/src/routes/_app/settings.tsx +13 -0
  193. package/src/routes/_app.tsx +13 -0
  194. package/style.css +8 -23
  195. package/tailwind.css +12 -0
  196. package/theme.css +5 -0
  197. package/dist/AddDriveModal-xAw48kdl.js.map +0 -1
  198. package/dist/ClearStorageModal-Czo-h6OE.js.map +0 -1
  199. package/dist/ConfirmDocumentUpgradeModal-FUOhZsk7.js.map +0 -1
  200. package/dist/CreateDocumentModal-C45W8J0V.js.map +0 -1
  201. package/dist/DebugSettingsModal-BUkre5Ke.js.map +0 -1
  202. package/dist/DeleteDriveModal-Dug84t1j.js.map +0 -1
  203. package/dist/DeleteItemModal-mMzy3V8o.js.map +0 -1
  204. package/dist/DisclaimerModal-DvpD5dPM.js.map +0 -1
  205. package/dist/DocumentVersionUnsupportedModal-C3Q0V75l.js.map +0 -1
  206. package/dist/DownloadDocumentWithErrorsModal-IKl0ljQb.js.map +0 -1
  207. package/dist/DriveAuthRequiredModal-DVK7ZQzO.js.map +0 -1
  208. package/dist/DriveSettingsModal-C6-mRQiv.js.map +0 -1
  209. package/dist/InspectorModal-C-dm0iSW.js.map +0 -1
  210. package/dist/LoginModal-CybbOm3N.js.map +0 -1
  211. package/dist/MissingPackageModal-nBnExqO0.js +0 -49
  212. package/dist/MissingPackageModal-nBnExqO0.js.map +0 -1
  213. package/dist/OpenFileDocumentsModal-DEcFBZ5I.js.map +0 -1
  214. package/dist/SettingsModal-CRBkw7d0.js +0 -569
  215. package/dist/SettingsModal-CRBkw7d0.js.map +0 -1
  216. package/dist/UpgradeDriveModal-_8t9slxQ.js.map +0 -1
  217. package/dist/app-loader-DkQhle_a.js +0 -4
  218. package/dist/app-loader-lsCT8EWA.js +0 -2244
  219. package/dist/app-loader-lsCT8EWA.js.map +0 -1
  220. package/dist/build-info-N6D-34wu.js.map +0 -1
  221. package/dist/components-DHzkxxly.js +0 -4
  222. package/dist/connect.config-DaHDEUrw.js.map +0 -1
  223. package/dist/connection-state-3w4liC1X.js.map +0 -1
  224. package/dist/load-BxUCaDLH.js.map +0 -1
  225. package/dist/pglite-major-B39aOEiE.js.map +0 -1
  226. package/dist/pglite-migrate-core-Boxqqx-c.js.map +0 -1
  227. package/dist/preferences-store-_5Cw4_YV.js.map +0 -1
  228. package/dist/reactor-Bg0Y9sdl.js.map +0 -1
  229. package/dist/runtime-config-DL3QjcfM.js +0 -24
  230. package/dist/runtime-config-DL3QjcfM.js.map +0 -1
  231. package/dist/sentry-QXKgQmr2.js +0 -15
  232. package/dist/sentry-QXKgQmr2.js.map +0 -1
  233. package/dist/use-renown-login-Cf3va6u_.js.map +0 -1
  234. package/dist/useRegistryPackages-BnUcL_nZ.js +0 -390
  235. package/dist/useRegistryPackages-BnUcL_nZ.js.map +0 -1
package/CUSTOMIZING.md ADDED
@@ -0,0 +1,80 @@
1
+ # Customizing Connect
2
+
3
+ How a Powerhouse project (scaffolded by `ph init`) changes what Connect shows: its own pages, sidebar links, settings tabs, and the layout around them.
4
+
5
+ ## TL;DR
6
+
7
+ Connect routes with [TanStack Router](https://tanstack.com/router) file routes. A project adds file routes to `hosts/connect/routes/`, and `ph connect build`, `ph connect studio` and `ph connect preview` mount them beside Connect's own routes in one router.
8
+
9
+ ```
10
+ hosts/connect/routes/
11
+ ├── _app.tsx optional: replaces Connect's layout (sidebar)
12
+ ├── _app/
13
+ │ ├── inventory.tsx /inventory, inside the layout
14
+ │ └── settings/
15
+ │ └── inventory.tsx /settings/inventory, a settings tab
16
+ └── status.tsx /status, a full page without the layout
17
+ ```
18
+
19
+ - A file in `_app/` renders inside Connect's layout, with the sidebar.
20
+ - Any other file renders as a full page.
21
+ - A route lists itself in the sidebar with `staticData.nav`, and adds a settings tab with `staticData.settings`.
22
+ - Route loaders read the app's PH store from the router context.
23
+
24
+ Connect's runtime settings (app name, drives, Renown, package registry) are the other way to customize it. They live in `powerhouse.config.json`; see [RUNTIME-CONFIG.md](./RUNTIME-CONFIG.md).
25
+
26
+ ## Guides
27
+
28
+ | Guide | Covers |
29
+ | --- | --- |
30
+ | [Pages, sidebar links and settings tabs](./docs/customizing/pages.md) | Add a page, list it in the sidebar, hide the sidebar on it, add a settings tab, set the page title. |
31
+ | [Layout and the loading screen](./docs/customizing/layout.md) | Replace the sidebar or the whole layout; what the prerendered loading screen shows. |
32
+ | [Data and navigation](./docs/customizing/data-and-navigation.md) | Route loaders, the open drive and document, editor props, typed search params, navigating from editors. |
33
+ | [Override Connect's routes](./docs/customizing/overrides.md) | Replace home, the drive view, the open document, settings or the 404 page; slow routes, not found and errors. |
34
+ | [Modals](./docs/customizing/modals.md) | Routed modals, replacing a modal's view, framing every modal. |
35
+ | [Styles and branding](./docs/customizing/styles-and-branding.md) | The project's Tailwind build and theme tokens; app name and favicon per host. |
36
+ | [Hosts and plugins](./docs/customizing/hosts-and-plugins.md) | Routes per host, host plugins, the generic plugin and a plugin's UI. |
37
+ | [Extend Connect from a package](./docs/customizing/packages.md) | A package's routes in every Connect that loads it; registering routes from code. |
38
+ | [Types, troubleshooting and upgrading](./docs/customizing/types-and-troubleshooting.md) | The generated route tree, common symptoms, `ph migrate`. |
39
+
40
+ Coding agents start from the [customize-connect skill](./skills/customize-connect/SKILL.md), which links to these guides.
41
+
42
+ ## UI screenshots of core's views
43
+
44
+ `ui:shots` in `@powerhousedao/connect-core` renders core's views in a real Connect and saves one PNG per scene to `packages/connect-core/.ui-shots/` (gitignored):
45
+
46
+ ```sh
47
+ pnpm --filter @powerhousedao/connect-core ui:serve # Connect plus a browser window on seeded drives
48
+ pnpm --filter @powerhousedao/connect-core ui:shots # every scene
49
+ pnpm --filter @powerhousedao/connect-core ui:shots document-json --theme dark
50
+ pnpm --filter @powerhousedao/connect-core ui:shots --list
51
+ ```
52
+
53
+ - Connect is a production build of `test/versioned-documents` (`ph connect build --outDir .ph/ui-shots/dist`), served by `ph connect preview` on `:4350` (`UI_SHOTS_CONNECT_PORT`, 4350-4359). The stack starts it unless the port answers, stops what it started, and rebuilds when the connect-core, Connect, builder-tools or project sources are newer than the build. `UI_CONNECT_DEV=1` runs `ph connect studio` instead.
54
+ - Each browser context overrides the served `powerhouse.config.json` with `connect.composition: []`, so the generic plugin is absent and core's views show. `--generic` keeps the classic chrome, for comparison.
55
+ - Each run seeds local drives through Connect's reactor: folders, a Todo document, Reactor Group documents (no editor, so the JSON view) and a drive whose `preferredEditor` is a drive app.
56
+ - Flags: `--width`, `--height`, `--out`; `UI_SHOTS_VERBOSE=1` prints the server logs. Scenes live in `SCENES` in `packages/connect-core/scripts/ui-shots.ts`.
57
+
58
+ ## Reference: key files
59
+
60
+ | File | What it holds |
61
+ | --- | --- |
62
+ | `apps/connect/src/routes/` | Connect's routes, which a project's files override: core's `options` and core's views, which plugins' UI replaces. |
63
+ | `packages/connect-core/src/routes/` | Core's routes: each file's `options` and core's view. |
64
+ | `packages/connect-core/src/plugins/plugin-ui.ts` | Loading, merging and applying plugins' UI. |
65
+ | `apps/connect/src/generic/ui.tsx` | The generic plugin's UI. |
66
+ | `apps/connect/src/layout/index.ts` | The `@powerhousedao/connect/layout` exports: core's layout parts. |
67
+ | `apps/connect/src/generic/index.ts` | The `@powerhousedao/connect/generic` exports: the generic plugin's parts, with core's. |
68
+ | `packages/connect-core/src/router/sidebar.ts` | `staticData.nav` and `staticData.sidebar`. |
69
+ | `packages/connect-core/src/router/settings.ts` | `staticData.settings`. |
70
+ | `packages/connect-core/src/router/drive-route-loader.ts` | `ConnectRouterContext`. |
71
+ | `packages/connect-core/src/router/search.ts` | Search param parsing and the global params. |
72
+ | `packages/connect-core/src/router/titles.ts` | Connect's titles. |
73
+ | `packages/builder-tools/connect-utils/vite-plugins/connect-routes.ts` | Routes folder lookup and tree generation. |
74
+ | `apps/connect/tailwind.css` | Connect's Tailwind source, which a project's `style.css` imports. |
75
+ | `apps/connect/theme.css` | Connect's tokens without its classes, which a package's stylesheet references. |
76
+ | `packages/codegen/src/file-builders/boilerplate/migrate-style.ts` | `style.css` on `ph migrate`, and the package stylesheet `ph build` compiles. |
77
+ | `packages/builder-tools/connect-utils/vite-plugins/host-stylesheet.ts` | The host's `style.css`, added to the project's in the page's build. |
78
+ | `apps/connect/src/prerender/shell-css.ts` | The loading screen's CSS, built by Tailwind's compiler. |
79
+ | `packages/reactor-browser/src/hooks/navigation.ts`, `link-props.ts` | The navigation API for editors. |
80
+ | `test/versioned-documents/hosts/connect/routes/` | A working example project. |
package/README.md CHANGED
@@ -62,6 +62,34 @@ Connect will be available at: `http://localhost:4000/develop/powerhouse/connect`
62
62
 
63
63
  Connect's runtime settings (renown URL, package registry, default drives, log level, etc.) live in `powerhouse.config.json` rather than environment variables. See [RUNTIME-CONFIG.md](./RUNTIME-CONFIG.md) for the full overview of how values are set, merged, and read by the SPA.
64
64
 
65
+ ## Routes
66
+
67
+ Connect routes with [TanStack Router](https://tanstack.com/router) file routes. Core's routes live in `@powerhousedao/connect-core` (`packages/connect-core/src/routes/`): the root route, the pathless `_app` layout, and `/`, `/d/$driveSlug/{-$nodeSlug}`, `/settings` with its Appearance and Packages tabs, and the 404 catch-all `$` inside it. Connect's `src/routes/` has one file per core route: it spreads core's `options` and shows core's view, which the active plugins' UI replaces (the generic plugin draws the sidebar, home, drive views and its own settings tabs). `src/routeTree.gen.ts` is generated from them (`pnpm exec tsr generate`, or `vite dev`) and committed.
68
+
69
+ A project customizes Connect with file routes in `hosts/connect/routes/`, which `ph vetra`, `ph connect studio`, `ph connect build` and `ph build` mount beside Connect's routes in one router:
70
+
71
+ ```
72
+ hosts/connect/routes/
73
+ ├── _app.tsx optional: replaces Connect's layout
74
+ ├── _app/
75
+ │ ├── reports.tsx /reports, inside the layout
76
+ │ ├── d/$driveSlug.tsx overrides Connect's drive view
77
+ │ └── settings/
78
+ │ └── reports.tsx /settings/reports, a settings tab
79
+ └── hello.tsx /hello, a full page without the layout
80
+ ```
81
+
82
+ - A file in `_app/` renders inside the layout; its id starts with `/_app`, e.g. `createFileRoute("/_app/reports")`, and its URL does not.
83
+ - A file at one of Connect's route paths overrides it by spreading that route's `options` (`@powerhousedao/connect/routes/...`). A route outside `_app/` at one of Connect's URLs fails the build.
84
+ - `staticData.nav` lists a route in the sidebar, `staticData.settings` makes it a settings tab, and `staticData.sidebar` hides or collapses the sidebar on its page.
85
+ - `ph connect build` prerenders the project's layout into `index.html` as the loading screen, with `_app`'s `pendingComponent` as its content.
86
+ - The tree is generated into `.ph/connect-routes.gen.ts`, which types `createFileRoute`, `Link` and `useNavigate` with the project's routes.
87
+ - Without a routes folder, Connect uses its prebuilt route tree.
88
+
89
+ [CUSTOMIZING.md](./CUSTOMIZING.md) indexes the task-by-task guides in [`docs/customizing/`](./docs/customizing/), and coding agents start from the [customize-connect skill](./skills/customize-connect/SKILL.md).
90
+
91
+ Code that does not build with Vite adds code routes with `registerConnectRoutes` from `@powerhousedao/connect/router`: it receives Connect's routes (`appRoute` for the layout, `rootRoute` for a full page, `settingsRoute` for a tab) and returns the routes to add; see [Extend Connect from a package](./docs/customizing/packages.md#register-routes-from-code).
92
+
65
93
  ## Troubleshooting
66
94
 
67
95
  - For a complete list of _Electron Forge_ options and requirements, visit the [official docs](https://github.com/electron-userland/electron-forge#usage).
@@ -0,0 +1,472 @@
1
+ # Connect Runtime Configuration
2
+
3
+ How runtime values reach the Connect SPA, where they're defined, who can change them, and how the SPA picks them up.
4
+
5
+ ## TL;DR
6
+
7
+ Connect's runtime configuration lives in a single JSON file: `powerhouse.config.json`. The file exists in two places — a hand-edited _source_ in the project root, and a built _dist_ that Connect actually serves at runtime. The SPA reads it once at boot via `fetch()` and never looks at environment variables for its own settings. Operators set values by editing the source file, passing CLI flags, running `ph connect config`, or — at deploy time — setting environment variables that a Docker entrypoint translates into the dist file.
8
+
9
+ ```
10
+ ┌──────────── ways to set a value ────────────┐
11
+ │
12
+ ph init (scaffold defaults) │
13
+ edit powerhouse.config.json by hand │
14
+ ph connect config --<field> <value> │
15
+ ph connect build --<field> <value> │
16
+ ph install --registry <url> │
17
+ PH_CONNECT_CONFIG_JSON env (deploy-time) │
18
+ │
19
+ └──────────────────────┬───────────────────────┘
20
+ │
21
+ ▼
22
+ powerhouse.config.json (dist)
23
+ │
24
+ │ fetch('/powerhouse.config.json')
25
+ ▼
26
+ Connect SPA — ConfigLoader cached at boot
27
+ │
28
+ getRuntimeConfig() / getConnectConfig()
29
+ ▼
30
+ consumed by Package Manager, Renown,
31
+ drive sidebar, router basename, etc.
32
+ ```
33
+
34
+ ## The file
35
+
36
+ Schema lives in `packages/builder-tools/connect-utils/runtime-config-schema.ts`. Shape (simplified):
37
+
38
+ ```jsonc
39
+ {
40
+ "$schema": "...",
41
+ "schemaVersion": 2,
42
+
43
+ // Top-level — project-wide, also read by ph-cli + Switchboard:
44
+ "packages": [
45
+ { "packageName": "@scope/pkg", "version": "1.0.0", "provider": "registry" }
46
+ ],
47
+ "packageRegistryUrl": "https://registry.vetra.io",
48
+ "localPackage": { "name": "...", "version": "..." } | null,
49
+
50
+ // Connect-only runtime values:
51
+ "connect": {
52
+ "branding": { "appName": "...", "homeBackground": "..." | null },
53
+ "app": { "logLevel": "info", "basePath": "/", "offline": true },
54
+ "renown": { "url": "...", "networkId": "eip155", "chainId": 1, "switchboardUrl": "..." | undefined, "adapters": {...} | undefined },
55
+ "drives": { "allowAddDrive": true, "defaultDrives": [...], "preserveStrategy": "...", "sections": {...} },
56
+ "packages": { "externalEnabled": true },
57
+ "sentry": { "dsn": null, "env": "dev", "tracing": false },
58
+ "openPanel": { "clientId": "", "apiUrl": "..." | undefined, "trackUiEvents": true, "trackOperations": true },
59
+ "reactor": { "featureFlags": { "documentDecisions": false, "authEnforcement": false, "authGroups": false, "authConditions": false }, "createSignaturePolicy": "v2-required", "unsupportedStoredDocuments": "refuse" },
60
+ "pwa": { ... } // build-time only, see below
61
+ }
62
+ }
63
+ ```
64
+
65
+ The defaults for the `connect.*` block are defined once in `packages/shared/connect/runtime-config.ts` as `DEFAULT_CONNECT_CONFIG`. They are the floor of the precedence ladder, the scaffolded template for new projects, and the merge base that guarantees the SPA never sees a partially-populated `connect.*` block.
66
+
67
+ ### Renown in-page sign-in (`connect.renown.switchboardUrl` + `adapters`)
68
+
69
+ By default Connect authenticates by **redirecting** to the Renown portal (`connect.renown.url`). Setting `connect.renown.switchboardUrl` enables **in-page** sign-in — the user signs a Renown credential inside Connect and it is written/logged in via that switchboard, with no redirect. If it isn't set, or no adapter can produce a wallet session, Connect falls back to the redirect flow automatically.
70
+
71
+ `connect.renown.adapters` selects which wallet adapters power in-page sign-in. Presence of a key enables that adapter. Connect ships with every adapter's peer dependencies installed, so operators need only edit the config; each adapter's libraries are still lazy-loaded on the first login click, so a privy-only deployment never downloads the RainbowKit chunk. (Standalone apps embedding `RenownWalletProvider` install peers per adapter they import — see the [Renown SDK README](../../packages/renown/README.md#wallet-adapters-in-page-sign-in).) Connect's config-to-adapter mapping lives in `src/components/renown-adapter-descriptors.ts`.
72
+
73
+ ```jsonc
74
+ "renown": {
75
+ "url": "https://www.renown.id", // redirect fallback
76
+ "switchboardUrl": "https://switchboard.example/graphql", // enables in-page auth
77
+ "adapters": {
78
+ "rainbow": { "walletConnectProjectId": "..." }, // external wallets
79
+ "privy": { "appId": "...", "methods": ["google", "email"] } // social / email
80
+ }
81
+ }
82
+ ```
83
+
84
+ Only **public** identifiers belong here (`walletConnectProjectId`, Privy `appId`/`clientId`). Never place a Privy **App Secret** in this file — it is server-only and this file is fetched by the browser. Each configured social/email method must also be enabled in the Privy dashboard, and Connect's origin allowlisted there.
85
+
86
+ `switchboardUrl` can be overridden at build time with `ph connect config --renown-switchboard-url <url>` (or the `PH_CONNECT_CONFIG_JSON` env override); `adapters` is set via the config file / `PH_CONNECT_CONFIG_JSON`.
87
+
88
+ `chainId` (default `1`) is the chain Renown issues credentials on. It is part of the user's DID, so the same wallet on another chain is a different user, and sign-in from a wallet on a different chain is rejected. Setting it moves three things together: the credential, the bearer token — including the reactor worker's, which builds its own crypto and receives the chain through its construct message since it cannot read runtime config — and the chain the wallet UI offers, so the user is prompted to switch rather than rejected at the end of the flow.
89
+
90
+ Only chains Connect bundles can be offered (`1`, `11155111`, `137`, `10`, `42161`, `8453`); any other id logs an error and leaves in-page sign-in unusable. `networkId` remains unread — `did:pkh` identities here are always `eip155`.
91
+
92
+ ### Reactor enforcement flags (`connect.reactor.featureFlags`)
93
+
94
+ The reactor Connect runs in the browser takes the same four enforcement flags a
95
+ switchboard does: `documentDecisions`, `authEnforcement`, `authGroups`,
96
+ `authConditions`. Each requires the one before it, and the reactor refuses to
97
+ build a set that skips one. All default `false`.
98
+
99
+ ```jsonc
100
+ "reactor": {
101
+ "featureFlags": {
102
+ "documentDecisions": true,
103
+ "authEnforcement": true,
104
+ "authGroups": true,
105
+ "authConditions": true
106
+ }
107
+ }
108
+ ```
109
+
110
+ These are the one part of `connect.*` that is not a local preference. A flag
111
+ changes how stored history is replayed, and a replay verdict is a consensus
112
+ outcome, so **a Connect must carry the same flags as the fleet it syncs with**.
113
+ A flags-off Connect syncing an enforcing switchboard applies operations that
114
+ switchboard denied and the two diverge. Set them per fleet, alongside the
115
+ switchboard's `REACTOR_*` env vars (see `apps/switchboard/README.md`).
116
+
117
+ Both reactor hosts read them: the main-thread reactor takes the value from this
118
+ file directly, and the SharedWorker gets it in its construct message, for the
119
+ same reason it gets `renown.chainId` — a worker has no runtime config of its
120
+ own. There is deliberately no query-param or localStorage override, unlike
121
+ `connect.instance.reactorWorker`: a per-tab flag would be a per-node flag.
122
+
123
+ The flag set is part of the worker's version fingerprint, so a flip is picked up
124
+ even though it isn't a rebuild. A tab whose flags differ from the running
125
+ worker's is told to reload onto a fresh worker, exactly as it would be after a
126
+ new build — without that, the worker would keep enforcing the flags it booted
127
+ with while the tab believed the new set was live. Other tabs still on the old
128
+ worker reload as they refresh.
129
+
130
+ With `authEnforcement` on, both hosts install the Renown trust policy that
131
+ switchboard installs under `REACTOR_AUTH_ENFORCEMENT`: a signed write is
132
+ accepted when a Renown credential binds its key to the wallet it claims, and
133
+ the logged-in user's own key is accepted without a lookup. Credentials are
134
+ read from `connect.renown.switchboardUrl`, or the switchboard `connect.renown.url`
135
+ advertises, else Renown's REST API at `connect.renown.url`, so that endpoint must
136
+ be reachable from the browser. With neither set, the reactor fails to build
137
+ rather than refuse every signed write. The worker gets both URLs in its construct
138
+ message and keeps the ones the first tab booted it with.
139
+
140
+ ### Creation signature policy (`connect.reactor.createSignaturePolicy`)
141
+
142
+ What the documents and drives Connect creates are born as: `"v2-required"`
143
+ (the default) or `"legacy"`. A v2-required document accepts only v2 action
144
+ signatures and takes a content-addressed id. Set `"legacy"` while any reactor
145
+ Connect syncs with predates v2-required documents; existing documents keep
146
+ their policy either way, and the setting does not change what Connect accepts.
147
+
148
+ ```jsonc
149
+ "reactor": { "createSignaturePolicy": "legacy" }
150
+ ```
151
+
152
+ The main-thread reactor reads it from this file; the SharedWorker gets it in its
153
+ construct message and keeps the value the first tab booted it with. It is not
154
+ part of the worker's version fingerprint.
155
+
156
+ ### Stored documents this build does not run (`connect.reactor.unsupportedStoredDocuments`)
157
+
158
+ A reactor refuses to boot when the browser's store holds documents created at a
159
+ protocol version the build does not run, for example after rolling Connect back
160
+ to a release that predates one. Connect then shows "Connect cannot open this
161
+ browser's documents" with the versions and document count, instead of the app.
162
+ There are two ways forward: serve a Connect build that runs those versions, or
163
+ accept them read-only:
164
+
165
+ ```jsonc
166
+ "reactor": { "unsupportedStoredDocuments": "read-only" }
167
+ ```
168
+
169
+ `"refuse"` is the default. With `"read-only"` the reactor boots, logs a warning,
170
+ and refuses every write into those documents and every operation received for
171
+ them; the rest of the store works as usual. Connect has no in-app button for it:
172
+ the setting is the operator's choice, so it goes in this file (or
173
+ `PH_CONNECT_CONFIG_JSON`), and the boot screen's Reload picks up the change.
174
+ Both reactor hosts read it; the SharedWorker gets it in its construct message.
175
+ A worker that refused retries the build on the next tab's connect, so the new
176
+ value takes effect without closing other tabs.
177
+
178
+ ### Multi-reactor routing (`connect.instance.multiReactor`)
179
+
180
+ Experimental, optional, default `false`. When on, Connect reads and writes
181
+ through a router over its own reactor and the Switchboard of the first remote
182
+ default drive (`drives.defaultDrives[].url`), and its reactor gains a local sync
183
+ channel.
184
+
185
+ ```jsonc
186
+ "instance": { "multiReactor": true }
187
+ ```
188
+
189
+ It is part of the worker's version fingerprint, so like the enforcement flags
190
+ it is set in this file only, with no query-param or localStorage override.
191
+
192
+ ## Setting values — the precedence ladder
193
+
194
+ When `ph connect build` runs, the _dist_ `powerhouse.config.json` is produced by deep-merging in this order (lowest → highest):
195
+
196
+ ```
197
+ DEFAULT_CONNECT_CONFIG < source.connect < CLI flag overrides
198
+ ```
199
+
200
+ Plus the top-level field:
201
+
202
+ ```
203
+ packageRegistryUrl = cliPackageRegistryUrl ?? source.packageRegistryUrl ?? null
204
+ ```
205
+
206
+ Each layer can supply a partial value; missing leaves fall back to the layer below. Arrays replace (they don't append), and `undefined` in a patch means "leave alone".
207
+
208
+ Two fields interact with the service worker and deserve a caveat:
209
+
210
+ - **`connect.branding.favicon` is build-time only.** A file relative to the project, served by `ph connect studio` and built as `icon.ico` by `ph connect build`; the dist file leaves it out.
211
+ - **`connect.pwa` (the project's own block) is build-time only.** `ph connect build` merges it (together with build-time package `pwa` fragments) into the base `manifest.webmanifest` and the injectManifest `service-worker.js` — including the manifest's `icons`, `file_handlers` (the built-in `.phd`/`.phdm` OS file association plus any contributed types) and `launch_handler`. The manifest's `categories` is not authored here — it is derived from the top-level `category` field of every contributing `powerhouse.manifest.json` (project + packages), unioned. It is carried along in the dist file for transparency, but the SPA never reads the project block — editing the dist copy or injecting it via `PH_CONNECT_CONFIG_JSON` has no effect. See the Academy page "Configure the PWA" for the merge semantics.
212
+ - **Packages installed AT RUNTIME extend the PWA config the same way build-time packages do.** The service worker serves `manifest.webmanifest` dynamically and reads its runtime-caching / navigate-fallback contributions from IndexedDB `ph-pwa` (mirrored by `BrowserPackageManager.#syncPwaFragments`), so a runtime package's manifest members, overridden scalars, `runtimeCaching` rules and `navigateFallbackDenylist` patterns all apply without a rebuild. Two guardrails vs. build-time: the manifest merge is fragment-wins **except `start_url`/`scope`** (protected, so an end-user-installed package can't re-scope the app), and `.phd`/`.phdm` stay first-registered. Timing caveats (not build-vs-runtime): `file_handlers`/`launch_handler` are captured by the OS at PWA install time (Chrome re-reads on its own periodic manifest check — never mid-session; content-based routing opens `.phd`/`.phdm` regardless), and `runtimeCaching`/`navigateFallbackDenylist` are read at worker startup (full effect on the worker's next activation). Only `globPatterns`/`globIgnores`/`maximumFileSizeToCacheInBytes` stay build-time only — they drive the workbox precache list baked at build.
213
+ - **`connect.app.offline` is hybrid.** At build time it decides whether a precaching worker or a self-destroying one is emitted; at boot the SPA reads it to register or unregister the worker (`apps/connect/src/components/app.tsx`, default `true`). Flipping it to `false` at deploy time therefore unregisters the worker on the next load, but flipping it to `true` cannot conjure a worker the build didn't emit.
214
+
215
+ ### The five ways to feed a value into a layer
216
+
217
+ | Way | Lands in | When to use |
218
+ | ----------------------------------------------------------- | ----------------------------------------------- | -------------------------------------------------------------------- |
219
+ | `ph init` template | source file | Initial scaffold; gives every project a working default |
220
+ | Manual edit of `<project>/powerhouse.config.json` | source file | Local dev tweaks; checked into git |
221
+ | `ph connect config --<field> <value>` (or `--json '{...}'`) | source **and** dist (dual-write) | Quick CLI edit that takes effect on next refresh, without rebuilding |
222
+ | `ph connect build --<field> <value>` (or `--json '{...}'`) | dist (CLI override layer) | One-off override at build time, e.g. CI baking a different `--base` |
223
+ | Docker entrypoint env var `PH_CONNECT_CONFIG_JSON` | dist file at container start, **operator-wins** | Per-deployment knobs without rebuilding the image |
224
+
225
+ Two special-case writers also exist:
226
+
227
+ - `ph install --registry <url>` writes the top-level `packageRegistryUrl` (overwrites when `--registry` is explicit, otherwise preserves existing).
228
+ - `ph vetra` passes a programmatic `callerOverride` to `ph connect studio` so default drives don't have to be tipped on every invocation.
229
+
230
+ ### Notes on each method
231
+
232
+ **Manual edit.** The source `powerhouse.config.json` lives in the project root next to `package.json`. It carries top-level keys for other tooling too (`studio.port`, `reactor.*`, `auth.*`, `documentModelsDir`, etc.); those keys pass through Connect's loader untouched.
233
+
234
+ **`ph connect config`.** Four modes (mutually exclusive — positional, `--get`, `--json`, and field flags cannot be combined):
235
+
236
+ - No args → list mode: prints the effective `connect.*` block (defaults + source).
237
+ - `<key>` (positional) or `--get <dotted.path>` → prints a single value at the dotted path (also works for top-level `packageRegistryUrl`).
238
+ - `<key> <value>` (positional) or `--<field> <value>` → set mode: Ajv-validates the value against the schema at that path and dual-writes to source and dist (dist is skipped silently if no build has happened yet). Coercion is JSON-aware — `true`/`false`/numbers parse correctly; arrays and objects should go through `--json` instead.
239
+ - `--json '{...}'` → bulk-set mode: validates the full patch and dual-writes.
240
+
241
+ **`--json` payload shape.** Both `ph connect config --json` and `ph connect build --json` take the `connect.*` block **without** the `connect` wrapper, as nested objects (not dotted keys). A top-level `packageRegistryUrl` is also accepted. The payload is Ajv-validated against the runtime schema: an unknown key, a `{"connect":{...}}` wrapper, a dotted key such as `"app.workflowsEnabled"`, or a wrong type fails the command instead of being dropped.
242
+
243
+ ```bash
244
+ # Enables workflows and adds a default drive.
245
+ ph connect build --json '{"app":{"workflowsEnabled":true},"drives":{"defaultDrives":[{"url":"http://localhost:4001/d/my-workflows","name":"My workflows"}]}}'
246
+ ```
247
+
248
+ **`ph connect build` overrides.** Three combinable forms (last wins on collision): `<key> <value>` positional, `--<field> <value>` per-field flag, or `--json '{...}'` bulk. The same shared spec drives both `build` and `config`, so the positional grammar matches. **`--base` IS available here** (build-time field). The 4 flags inherited from `commonArgs` (`--base`, `--log-level`, `--default-drives-url`, `--drive-preserve-strategy`) carry cmd-ts defaults, so they're gated through `wasFlagExplicitlyPassed` — if the user didn't type the flag, the source value wins. CLI overrides beat source. Build has no read mode; passing only `<key>` without `<value>` errors with a pointer to `ph connect config <key>`.
249
+
250
+ **`--base` is build-time only.** `ph connect build --base /foo` writes `connect.app.basePath` AND bakes the value into the Vite bundle's asset URLs AND templates the nginx config. `ph connect config --base /foo` would only write the first one, leaving the SPA's router and the deployed assets disagreeing — so `ph connect config` rejects `--base` up front with an actionable error pointing at `ph connect build --base`.
251
+
252
+ **Docker entrypoint.** `docker/connect-entrypoint.sh` runs at container start and accepts a single env var, `PH_CONNECT_CONFIG_JSON`, carrying a full `powerhouse.config.json` payload, with the `connect` wrapper (unlike `--json`, which takes the `connect.*` block alone). It deep-merges that JSON into the dist file with **operator-wins semantics**: a concrete value in the env JSON (including `false`/`""`/`[]`/`0`) overwrites whatever the build baked; a `null` leaf (or an omitted key) keeps the file's value, so baked defaults only apply where the operator expressed no opinion. One exception: `connect.app.basePath` is stripped from the payload — the base path is baked into the bundled asset URLs and cannot be changed at runtime (rebuild with `--base`, or use `--dynamic-base`). This is the only env-var path still active — the SPA itself does not read env vars. Operators get the deployment-time knob without env vars leaking into runtime behaviour.
253
+
254
+ ```bash
255
+ docker run \
256
+ -e PH_CONNECT_CONFIG_JSON='{"connect":{"renown":{"url":"https://renown.staging"},"app":{"logLevel":"debug"}}}' \
257
+ connect:latest
258
+ ```
259
+
260
+ Invalid JSON (parse error or non-object payload) aborts startup with a clear stderr message rather than silently dropping the operator payload. The shell layer keeps `PH_CONNECT_BASE_PATH` separate because nginx needs it for URL templating before any JSON is touched.
261
+
262
+ ## How Connect reads the file at boot
263
+
264
+ `apps/connect/main.tsx`:
265
+
266
+ ```tsx
267
+ import { createRoot } from "react-dom/client";
268
+ import { loadRuntimeConfig } from "./src/runtime-config.js";
269
+
270
+ if (!window.ph) window.ph = {};
271
+
272
+ // Bootstrap the runtime config BEFORE AppLoader's transitive imports
273
+ await loadRuntimeConfig();
274
+ const { AppLoader } = await import("./src/components/app-loader.js");
275
+
276
+ createRoot(document.getElementById("root")!).render(<AppLoader />);
277
+ ```
278
+
279
+ Two ordering tricks:
280
+
281
+ 1. **Top-level await** on `loadRuntimeConfig()` blocks module evaluation until the fetch resolves.
282
+ 2. **Dynamic import** of `AppLoader` so any module that calls `getRuntimeConfig()` at import time (synchronous read from the cache) only runs _after_ step 1.
283
+
284
+ Together these prevent a cache-empty race where the SPA would have to fall back to defaults or throw.
285
+
286
+ `loadRuntimeConfig` (in `apps/connect/src/runtime-config.ts`) is a 4-line wrapper around the shared loader:
287
+
288
+ ```ts
289
+ const loader = new ConfigLoader(
290
+ new JsonConfigAdapter({
291
+ path: `${import.meta.env.BASE_URL}powerhouse.config.json`,
292
+ }),
293
+ );
294
+ ```
295
+
296
+ - `ConfigLoader` (in `packages/shared/connect/config-loader.ts`) wraps any `ConfigAdapter` with deep-merge-against-defaults and in-process caching.
297
+ - `JsonConfigAdapter` reads via `fetch()` when `window` is defined, via `fs` in Node.
298
+ - After `loadRuntimeConfig()` resolves once, any synchronous `getRuntimeConfig()` call returns the cached payload immediately.
299
+
300
+ Downstream consumers inside the SPA:
301
+
302
+ | File | Reads |
303
+ | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
304
+ | `apps/connect/src/connect.config.ts` | Re-exports the cached config behind getters (`getConnectConfig()`) so the rest of the SPA reads typed accessors instead of dotted paths |
305
+ | `apps/connect/src/hooks/useRegistryPackages.ts` | `getRuntimeConfig().packageRegistryUrl` |
306
+ | `apps/connect/src/store/reactor.ts` | Passes `packageRegistryUrl` to `BrowserPackageManager`; reads `connect.reactor.featureFlags`, `createSignaturePolicy` and `unsupportedStoredDocuments` for both reactor hosts |
307
+ | Renown auth flow | Reads `connect.renown.*` |
308
+ | Drives sidebar | Reads `connect.drives.*` |
309
+ | Router | Reads `connect.app.basePath` |
310
+ | `apps/connect/src/components/app.tsx` | Reads `connect.app.offline` to register or unregister the service worker |
311
+
312
+ A hard refresh in the browser tears down the module graph; the next module evaluation runs `loadRuntimeConfig()` again and the SPA picks up whatever the dist file holds now. This is the path operators use after `ph connect config --renown-url X`: write the new value, refresh the tab.
313
+
314
+ ## Other consumers of the same file
315
+
316
+ The dist `powerhouse.config.json` is not a Connect-private artefact:
317
+
318
+ - **Switchboard** (Node) reads `packages[]` and `packageRegistryUrl` at startup via the same `ConfigLoader` + `JsonConfigAdapter` (Node branch).
319
+ - **`ph install` / `ph publish`** use `resolveRegistryUrl` to pick a registry with priority `--flag > PH_REGISTRY_URL env > config.packageRegistryUrl > DEFAULT_REGISTRY_URL`.
320
+
321
+ This is why `packageRegistryUrl` lives at the top level rather than nested under `connect.*` — it's a project-wide setting, not Connect-only.
322
+
323
+ ## Common operator workflows
324
+
325
+ **"I just want to point Connect at a different registry."**
326
+ Edit the project's `powerhouse.config.json`, set `"packageRegistryUrl": "https://my.registry"`, refresh Connect. Or `ph connect config --packages-registry https://my.registry`.
327
+
328
+ **"I want a subpath deploy (`/connect` instead of `/`)."**
329
+ `ph connect build --base /connect`. The CLI override lands in the dist `connect.app.basePath` and the bundled assets pick it up.
330
+
331
+ **"I want default drives to load automatically."**
332
+ `ph connect config --default-drives-url https://drive-a, https://drive-b`. The CSV is parsed into `connect.drives.defaultDrives[]` objects.
333
+
334
+ **"I want my project to boot with a preconfigured local drive."**
335
+ Add a local entry to `connect.drives.defaultDrives` in `powerhouse.config.json`:
336
+ `{"local": true, "id": "my-drive", "name": "My Drive", "icon": "https://…", "app": "powerhouse/generic-drive-explorer"}`.
337
+ On first boot Connect creates the drive in the user's local reactor with that id and opens the given app on it; later boots skip it (idempotent by id). The `--default-drives-url` flag only produces remote entries.
338
+
339
+ **"I'm deploying the docker image to a new environment and need to override renown."**
340
+ Set `PH_CONNECT_CONFIG_JSON='{"connect":{"renown":{"url":"https://renown.staging.example"}}}'` on the container. The entrypoint script deep-merges the JSON into the dist file before nginx starts (operator-wins); the SPA serves the new value on the very first request.
341
+
342
+ **"I need a different Sentry DSN per environment."**
343
+ Sentry config lives in `connect.sentry.*` of `powerhouse.config.json`. The DSN, environment label, and tracing flag are all runtime — one Docker image serves staging + prod by switching the env-supplied JSON:
344
+
345
+ ```bash
346
+ docker run -e PH_CONNECT_CONFIG_JSON='{
347
+ "connect": {
348
+ "sentry": { "dsn": "https://prod-key@sentry.io/1", "env": "prod", "tracing": true }
349
+ }
350
+ }' connect:latest
351
+ ```
352
+
353
+ `dsn: null` (the default) disables Sentry — the SPA never loads the Sentry SDK chunk. The Sentry **release** tag, in contrast, stays build-time (stamped via Vite's `define` from `WORKSPACE_VERSION`) so it always matches the sourcemap upload tag CI used.
354
+
355
+ **"I want OpenPanel analytics on this deployment."**
356
+ Set `connect.openPanel.clientId` (and `apiUrl` for a self-hosted OpenPanel):
357
+
358
+ ```bash
359
+ docker run -e PH_CONNECT_CONFIG_JSON='{
360
+ "connect": {
361
+ "openPanel": { "clientId": "<client-id>", "apiUrl": "https://openpanel.example/api" }
362
+ }
363
+ }' connect:latest
364
+ ```
365
+
366
+ An empty `clientId` (the default) keeps OpenPanel off, and events are only sent after the user accepts analytics cookies. The runtime values take precedence over the build-time `PH_CONNECT_OPENPANEL_*` env vars, which remain a fallback for builds that bake them.
367
+
368
+ **"I'm turning auth enforcement on for this fleet."**
369
+ Set the whole flag set on the container, matching the switchboard's `REACTOR_*` env vars exactly:
370
+
371
+ ```bash
372
+ docker run -e PH_CONNECT_CONFIG_JSON='{
373
+ "connect": {
374
+ "reactor": { "featureFlags": {
375
+ "documentDecisions": true, "authEnforcement": true,
376
+ "authGroups": true, "authConditions": true
377
+ } }
378
+ }
379
+ }' connect:latest
380
+ ```
381
+
382
+ Partial sets are rejected at boot — `authConditions` requires `authGroups`, which requires `authEnforcement`, which requires `documentDecisions`. In worker mode, confirm what the running worker actually enforces in the inspector modal's worker panel ("Enforcement flags").
383
+
384
+ **"I want to verify what Connect will actually use without booting it."**
385
+ `ph connect config` (no args) prints the effective `connect.*` block (defaults merged with source). `ph connect config connect.renown.url` (or the equivalent `--get connect.renown.url`) prints a single value.
386
+
387
+ ## Adding or changing a config field (developers)
388
+
389
+ A `connect.*` field has five artefacts that must stay in lockstep. The TS
390
+ constants are the source of truth; the two committed `*.schema.json` files are
391
+ generated from them. Miss a step and the schemas silently drift from the types.
392
+
393
+ 1. **Type** — `packages/shared/clis/types.ts`. Add the field to the relevant
394
+ `PHConnect*` type (e.g. `PHConnectPackages`).
395
+ 2. **Default** — `packages/shared/connect/runtime-config.ts`. Add the field's
396
+ default to `DEFAULT_CONNECT_CONFIG` so the SPA never sees it undefined.
397
+ 3. **Schema fragment** — `packages/shared/connect/schema-fragments.ts`. Declare
398
+ the field (type, description, `default`) in `phConnectRuntimeConfigSchema`.
399
+ Both committed schemas import this fragment, so declaring it once keeps the
400
+ source-config and runtime-config schemas in sync by construction.
401
+ 4. **Rebuild** the source-of-truth packages so the emit script sees the change:
402
+ ```bash
403
+ pnpm --filter=@powerhousedao/shared --filter=@powerhousedao/builder-tools build
404
+ ```
405
+ 5. **Regenerate** the committed JSON schemas:
406
+ ```bash
407
+ pnpm tsx scripts/emit-schemas.ts
408
+ ```
409
+ This rewrites `packages/builder-tools/connect-utils/runtime-config.schema.json`
410
+ and `packages/shared/clis/source-config.schema.json`. Commit both.
411
+
412
+ **`connect.pwa.*` fields have a sixth artefact.** The zod `PwaConfigSchema` /
413
+ `PwaManifestOverrideSchema` in `packages/shared/document-model/schemas.ts` is
414
+ the validator `ph connect build` actually runs against `connect.pwa` (via
415
+ `validateProjectPwaConfig`), and it is hand-maintained: `emit-schemas.ts` does
416
+ not regenerate it, and the coverage test below does not cover it (there is no
417
+ `pwa` default). The `z.ZodType<PHConnectPwa>` annotation only pins it to the TS
418
+ type, not to the schema fragment, and does not force it to gain a newly-added
419
+ optional field. So when you add a `connect.pwa.*` field, declare it there too —
420
+ the objects are strict (`z.strictObject`), so a field the schema doesn't know
421
+ fails the build as an unrecognized key rather than being silently dropped.
422
+
423
+ Then consume it in the SPA via `getRuntimeConfig().connect?.<block>?.<field>`
424
+ (or add a typed accessor in `apps/connect/src/connect.config.ts`).
425
+
426
+ Optional, depending on the field:
427
+
428
+ - **CLI flag** — to expose `ph connect config/build --<field>`, wire it through
429
+ `packages/shared/clis/args/connect.ts` and `clis/ph-cli/src/utils/cli-connect-override.ts`
430
+ (see `externalEnabled` → `--external-packages` for the pattern).
431
+ - **Scaffold default** — if new projects should ship the field, add it to the
432
+ `ph init` template at `packages/codegen/src/templates/boilerplate/powerhouse.config.json.ts`.
433
+
434
+ The `runtime-config-schema.test.ts` coverage test asserts every key emitted from
435
+ `DEFAULT_CONNECT_CONFIG` has a matching schema declaration — it fails loudly if
436
+ you add a default (step 2) but skip the schema fragment (step 3).
437
+
438
+ ## Reference: key files
439
+
440
+ ```
441
+ packages/shared/connect/
442
+ ├ runtime-config.ts DEFAULT_CONNECT_CONFIG, types, buildRuntimeConfig
443
+ ├ config-loader.ts ConfigLoader, ConfigAdapter, deepMerge
444
+ └ json-adapter.ts JsonConfigAdapter (browser fetch | Node fs)
445
+
446
+ packages/builder-tools/connect-utils/
447
+ ├ runtime-config-schema.ts JSON Schema (Ajv)
448
+ └ vite-plugins/ph-config.ts Emits dist file & serves /powerhouse.config.json in dev
449
+
450
+ clis/ph-cli/src/
451
+ ├ utils/cli-connect-override.ts buildConnectFlagPatch, wasFlagExplicitlyPassed, buildCliConnectOverride
452
+ ├ utils/connect-config-validation.ts validateConnectPatch (Ajv)
453
+ ├ services/connect-config.ts `ph connect config` handler
454
+ ├ services/connect-studio.ts `ph connect studio` (accepts callerOverride)
455
+ ├ services/vetra.ts `ph vetra` (constructs callerOverride)
456
+ ├ commands/install.ts `ph install` (writes packageRegistryUrl)
457
+ └ utils.ts updateConfigFile
458
+
459
+ apps/connect/
460
+ ├ main.tsx top-level await + dynamic import (boot race fix)
461
+ └ src/runtime-config.ts loadRuntimeConfig, getRuntimeConfig
462
+
463
+ packages/codegen/src/templates/boilerplate/powerhouse.config.json.ts
464
+ └ `ph init` boilerplate template
465
+
466
+ docker/connect-entrypoint.sh
467
+ └ PH_CONNECT_CONFIG_JSON → dist overrides (jq deep-merge, operator-wins)
468
+ ```
469
+
470
+ ## Design principle, in one line
471
+
472
+ The SPA never reads `process.env`; it reads one JSON file. Everything an operator or developer wants to configure — by CLI, env, manual edit, scaffolding, or programmatic API — ends up in that file, with a single, clear precedence: `defaults < source < CLI override < PH_CONNECT_CONFIG_JSON` (the deploy-time env var wins wherever it supplies a concrete value).
@@ -1,11 +1,11 @@
1
1
 
2
- !function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="12b7a290-1f56-53ad-9cc5-b150c58de802")}catch(e){}}();
3
- import { r as toast } from "./toast-BXIGd4Eb.js";
2
+ !function(){try{var e="undefined"!=typeof window?window:"undefined"!=typeof global?global:"undefined"!=typeof globalThis?globalThis:"undefined"!=typeof self?self:{},n=(new e.Error).stack;n&&(e._sentryDebugIds=e._sentryDebugIds||{},e._sentryDebugIds[n]="cb114064-0090-5da7-a317-5056a3e9d8b7")}catch(e){}}();
3
+ import { r as toast } from "./toast-C6WW-_O-.js";
4
4
  import { jsx } from "react/jsx-runtime";
5
- import { t } from "i18next";
6
- import { addDrive, addRemoteDrive, closePHModal, extractDriveSlugFromPath, fetchDriveInfo, getDrives, setSelectedDrive, useAppModules, usePHModal, waitForDocumentReady } from "@powerhousedao/reactor-browser";
7
5
  import { AddDriveModal as AddDriveModal$1 } from "@powerhousedao/design-system/connect";
8
- //#region src/utils/create-drive-app-options.ts
6
+ import { addDrive, addRemoteDrive, closePHModal, extractDriveSlugFromPath, fetchDriveInfo, getDrives, getFullReactorClient, getPHNavigation, getPHStore, setSelectedDrive, useAppModules, usePHModal, waitForDocumentReady } from "@powerhousedao/reactor-browser";
7
+ import { t } from "i18next";
8
+ //#region src/generic/pages/create-drive-app-options.ts
9
9
  const DRIVE_APP_RANK = {
10
10
  GenericDriveExplorer: 1,
11
11
  "vetra-drive-app": 2
@@ -20,7 +20,7 @@ function getCreateDriveAppOptions(appModules) {
20
20
  })).sort((a, b) => (DRIVE_APP_RANK[a.id] ?? 0) - (DRIVE_APP_RANK[b.id] ?? 0));
21
21
  }
22
22
  //#endregion
23
- //#region src/components/modal/modals/AddDriveModal.tsx
23
+ //#region src/generic/modals/AddDriveModal.tsx
24
24
  const REMOTE_DRIVE_NAV_TIMEOUT_MS = 3e4;
25
25
  function AddDriveModal() {
26
26
  const open = usePHModal()?.type === "addDrive";
@@ -53,8 +53,8 @@ function AddDriveModal() {
53
53
  try {
54
54
  const driveId = await addRemoteDrive(data.url, data.id);
55
55
  toast(t("notifications.addDriveSuccess"), { type: "connect-success" });
56
- const reactorClient = window.ph?.reactorClientModule?.client;
57
- const stillOnHome = () => !window.ph?.selectedDriveId && !extractDriveSlugFromPath(window.location.pathname);
56
+ const reactorClient = getFullReactorClient();
57
+ const stillOnHome = () => !getPHStore()?.selectedDriveId && !extractDriveSlugFromPath(getPHNavigation().location().pathname);
58
58
  (async () => {
59
59
  try {
60
60
  if (!reactorClient) return;
@@ -94,5 +94,5 @@ function AddDriveModal() {
94
94
  //#endregion
95
95
  export { AddDriveModal };
96
96
 
97
- //# sourceMappingURL=AddDriveModal-xAw48kdl.js.map
98
- //# debugId=12b7a290-1f56-53ad-9cc5-b150c58de802
97
+ //# sourceMappingURL=AddDriveModal-BjgmiHJr.js.map
98
+ //# debugId=cb114064-0090-5da7-a317-5056a3e9d8b7