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

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 (242) hide show
  1. package/CUSTOMIZING.md +80 -0
  2. package/README.md +28 -0
  3. package/RUNTIME-CONFIG.md +481 -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-DxBXLSmH.js} +11 -13
  7. package/dist/ClearStorageModal-DxBXLSmH.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-D1I-K2Gf.js} +9 -9
  15. package/dist/DebugSettingsModal-D1I-K2Gf.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-D85U4oKJ.js} +70 -30
  33. package/dist/InspectorModal-D85U4oKJ.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-B9c-CsKT.js} +16 -14
  37. package/dist/OpenFileDocumentsModal-B9c-CsKT.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-D5GEwpML.js +4 -0
  41. package/dist/app-loader-casiq2T2.js +1253 -0
  42. package/dist/app-loader-casiq2T2.js.map +1 -0
  43. package/dist/app-skeleton-BHgmbYld.js +4 -0
  44. package/dist/app-skeleton-ClRUYLE_.js +121 -0
  45. package/dist/app-skeleton-ClRUYLE_.js.map +1 -0
  46. package/dist/boot-CFPdHSqB.js +233 -0
  47. package/dist/boot-CFPdHSqB.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-Cn2f6llN.js} +10 -6
  51. package/dist/build-info-Cn2f6llN.js.map +1 -0
  52. package/dist/components-C4K5xyad.js +121 -0
  53. package/dist/components-C4K5xyad.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-BIpd8edR.js +49 -0
  66. package/dist/drive-icon-BIpd8edR.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-DcDV9hi4.js} +48 -46
  82. package/dist/load-DcDV9hi4.js.map +1 -0
  83. package/dist/load-runtime-config-Deq75NYr.js +14 -0
  84. package/dist/load-runtime-config-Deq75NYr.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-CzBsaUUd.js +524 -0
  91. package/dist/package-manager-CzBsaUUd.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/plugin-configs.d.ts +242 -0
  105. package/dist/plugin-configs.d.ts.map +1 -0
  106. package/dist/plugin-configs.js +26 -0
  107. package/dist/plugin-configs.js.map +1 -0
  108. package/dist/plugins-CegSox2x.js +263 -0
  109. package/dist/plugins-CegSox2x.js.map +1 -0
  110. package/dist/{preferences-store-_5Cw4_YV.js → preferences-store-CSqauT9V.js} +6 -25
  111. package/dist/preferences-store-CSqauT9V.js.map +1 -0
  112. package/dist/prerender.d.ts +38 -0
  113. package/dist/prerender.d.ts.map +1 -0
  114. package/dist/prerender.js +181 -0
  115. package/dist/prerender.js.map +1 -0
  116. package/dist/prerendered-shell-peKE7AqI.js +51 -0
  117. package/dist/prerendered-shell-peKE7AqI.js.map +1 -0
  118. package/dist/{pwa-manifest-link-DIgOSo2Q.js → pwa-manifest-link-DQRJpF0r.js} +3 -3
  119. package/dist/{pwa-manifest-link-DIgOSo2Q.js.map → pwa-manifest-link-DQRJpF0r.js.map} +1 -1
  120. package/dist/{reactor-Bg0Y9sdl.js → reactor-BGYR1N7Z.js} +509 -562
  121. package/dist/reactor-BGYR1N7Z.js.map +1 -0
  122. package/dist/reactor-chat-LAB-9G3G.js +50 -0
  123. package/dist/reactor-chat-LAB-9G3G.js.map +1 -0
  124. package/dist/reactor.worker.d.ts +2 -1
  125. package/dist/reactor.worker.js +478 -156
  126. package/dist/reactor.worker.js.map +1 -1
  127. package/dist/{registerServiceWorker-BSzbNfvz.js → registerServiceWorker-APlHkrmH.js} +5 -5
  128. package/dist/{registerServiceWorker-BSzbNfvz.js.map → registerServiceWorker-APlHkrmH.js.map} +1 -1
  129. package/dist/root-B1Pq9x6S.js +24 -0
  130. package/dist/root-B1Pq9x6S.js.map +1 -0
  131. package/dist/route-tree.d.ts +2220 -0
  132. package/dist/route-tree.d.ts.map +1 -0
  133. package/dist/route-tree.js +135 -0
  134. package/dist/route-tree.js.map +1 -0
  135. package/dist/route-views-2aB1ZZPP.js +55 -0
  136. package/dist/route-views-2aB1ZZPP.js.map +1 -0
  137. package/dist/route-views-CDVZytw4.js +60 -0
  138. package/dist/route-views-CDVZytw4.js.map +1 -0
  139. package/dist/route-views-D_873yb_.js +4 -0
  140. package/dist/route-views.d.ts +7 -0
  141. package/dist/route-views.d.ts.map +1 -0
  142. package/dist/route-views.js +4 -0
  143. package/dist/router-B0OQvO11.js +4 -0
  144. package/dist/router-Cu0PH6sh.js +46 -0
  145. package/dist/router-Cu0PH6sh.js.map +1 -0
  146. package/dist/router.d.ts +2 -0
  147. package/dist/router.js +3 -0
  148. package/dist/sentry-Cuc_Nbba.js +22 -0
  149. package/dist/sentry-Cuc_Nbba.js.map +1 -0
  150. package/dist/settings-CFn4TA0g.js +1090 -0
  151. package/dist/settings-CFn4TA0g.js.map +1 -0
  152. package/dist/settings-tabs-BC8gAacB.js +410 -0
  153. package/dist/settings-tabs-BC8gAacB.js.map +1 -0
  154. package/dist/shell-core-head.html +2 -0
  155. package/dist/shell-core.html +1 -0
  156. package/dist/shell-head.html +2 -0
  157. package/dist/shell-plugins.json +1 -0
  158. package/dist/shell.html +1 -0
  159. package/dist/start-connect.d.ts +7 -9
  160. package/dist/start-connect.d.ts.map +1 -1
  161. package/dist/start-connect.js +9 -8
  162. package/dist/start-connect.js.map +1 -1
  163. package/dist/store-lock-Bi3B9VJD.js +159 -0
  164. package/dist/store-lock-Bi3B9VJD.js.map +1 -0
  165. package/dist/style.css +3144 -764
  166. package/dist/{toast-BXIGd4Eb.js → toast-C6WW-_O-.js} +3 -3
  167. package/dist/{toast-BXIGd4Eb.js.map → toast-C6WW-_O-.js.map} +1 -1
  168. package/dist/ui-BOTsJPoc.js +66 -0
  169. package/dist/ui-BOTsJPoc.js.map +1 -0
  170. package/dist/{use-renown-login-Cf3va6u_.js → use-renown-login-dPpDOYq5.js} +4 -4
  171. package/dist/use-renown-login-dPpDOYq5.js.map +1 -0
  172. package/dist/workflows-C3qEvx1R.js +63 -0
  173. package/dist/workflows-C3qEvx1R.js.map +1 -0
  174. package/docs/customizing/data-and-navigation.md +232 -0
  175. package/docs/customizing/hosts-and-plugins.md +65 -0
  176. package/docs/customizing/layout.md +149 -0
  177. package/docs/customizing/modals.md +78 -0
  178. package/docs/customizing/overrides.md +113 -0
  179. package/docs/customizing/packages.md +39 -0
  180. package/docs/customizing/pages.md +136 -0
  181. package/docs/customizing/styles-and-branding.md +69 -0
  182. package/docs/customizing/types-and-troubleshooting.md +63 -0
  183. package/fonts.css +177 -0
  184. package/package.json +88 -26
  185. package/scripts/assert-plugin-configs.mjs +47 -0
  186. package/scripts/prerender-shell.ts +51 -0
  187. package/skills/customize-connect/SKILL.md +74 -0
  188. package/src/route-tree.ts +3 -0
  189. package/src/routeTree.gen.ts +235 -0
  190. package/src/router/index.ts +2 -0
  191. package/src/router/register.ts +9 -0
  192. package/src/routes/__root.tsx +12 -0
  193. package/src/routes/_app/$.tsx +13 -0
  194. package/src/routes/_app/d/$driveSlug/{-$nodeSlug}.tsx +13 -0
  195. package/src/routes/_app/d/$driveSlug.tsx +13 -0
  196. package/src/routes/_app/index.tsx +13 -0
  197. package/src/routes/_app/settings/appearance.tsx +13 -0
  198. package/src/routes/_app/settings/packages.tsx +13 -0
  199. package/src/routes/_app/settings.tsx +13 -0
  200. package/src/routes/_app.tsx +13 -0
  201. package/style.css +8 -23
  202. package/tailwind.css +12 -0
  203. package/theme.css +5 -0
  204. package/dist/AddDriveModal-xAw48kdl.js.map +0 -1
  205. package/dist/ClearStorageModal-Czo-h6OE.js.map +0 -1
  206. package/dist/ConfirmDocumentUpgradeModal-FUOhZsk7.js.map +0 -1
  207. package/dist/CreateDocumentModal-C45W8J0V.js.map +0 -1
  208. package/dist/DebugSettingsModal-BUkre5Ke.js.map +0 -1
  209. package/dist/DeleteDriveModal-Dug84t1j.js.map +0 -1
  210. package/dist/DeleteItemModal-mMzy3V8o.js.map +0 -1
  211. package/dist/DisclaimerModal-DvpD5dPM.js.map +0 -1
  212. package/dist/DocumentVersionUnsupportedModal-C3Q0V75l.js.map +0 -1
  213. package/dist/DownloadDocumentWithErrorsModal-IKl0ljQb.js.map +0 -1
  214. package/dist/DriveAuthRequiredModal-DVK7ZQzO.js.map +0 -1
  215. package/dist/DriveSettingsModal-C6-mRQiv.js.map +0 -1
  216. package/dist/InspectorModal-C-dm0iSW.js.map +0 -1
  217. package/dist/LoginModal-CybbOm3N.js.map +0 -1
  218. package/dist/MissingPackageModal-nBnExqO0.js +0 -49
  219. package/dist/MissingPackageModal-nBnExqO0.js.map +0 -1
  220. package/dist/OpenFileDocumentsModal-DEcFBZ5I.js.map +0 -1
  221. package/dist/SettingsModal-CRBkw7d0.js +0 -569
  222. package/dist/SettingsModal-CRBkw7d0.js.map +0 -1
  223. package/dist/UpgradeDriveModal-_8t9slxQ.js.map +0 -1
  224. package/dist/app-loader-DkQhle_a.js +0 -4
  225. package/dist/app-loader-lsCT8EWA.js +0 -2244
  226. package/dist/app-loader-lsCT8EWA.js.map +0 -1
  227. package/dist/build-info-N6D-34wu.js.map +0 -1
  228. package/dist/components-DHzkxxly.js +0 -4
  229. package/dist/connect.config-DaHDEUrw.js.map +0 -1
  230. package/dist/connection-state-3w4liC1X.js.map +0 -1
  231. package/dist/load-BxUCaDLH.js.map +0 -1
  232. package/dist/pglite-major-B39aOEiE.js.map +0 -1
  233. package/dist/pglite-migrate-core-Boxqqx-c.js.map +0 -1
  234. package/dist/preferences-store-_5Cw4_YV.js.map +0 -1
  235. package/dist/reactor-Bg0Y9sdl.js.map +0 -1
  236. package/dist/runtime-config-DL3QjcfM.js +0 -24
  237. package/dist/runtime-config-DL3QjcfM.js.map +0 -1
  238. package/dist/sentry-QXKgQmr2.js +0 -15
  239. package/dist/sentry-QXKgQmr2.js.map +0 -1
  240. package/dist/use-renown-login-Cf3va6u_.js.map +0 -1
  241. package/dist/useRegistryPackages-BnUcL_nZ.js +0 -390
  242. 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,481 @@
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": "...", "icon": "..." | null, "loader": "..." | { src, animation, size } | null },
53
+ "home": { "background": "..." | { color, layers: [{ src, position, width, height, fade, ... }] } | null },
54
+ "app": { "logLevel": "info", "basePath": "/", "offline": true },
55
+ "renown": { "url": "...", "networkId": "eip155", "chainId": 1, "switchboardUrl": "..." | undefined, "adapters": {...} | undefined },
56
+ "drives": { "allowAddDrive": true, "defaultDrives": [...], "preserveStrategy": "...", "sections": {...},
57
+ "icons": { localDrive, remoteDrive, folder, document, documents } | null },
58
+ "packages": { "externalEnabled": true },
59
+ "sentry": { "dsn": null, "env": "dev", "tracing": false },
60
+ "openPanel": { "clientId": "", "apiUrl": "..." | undefined, "trackUiEvents": true, "trackOperations": true },
61
+ "reactor": { "featureFlags": { "documentDecisions": false, "authEnforcement": false, "authGroups": false, "authConditions": false }, "createSignaturePolicy": "v2-required", "unsupportedStoredDocuments": "refuse" },
62
+ "pwa": { ... } // build-time only, see below
63
+ }
64
+ }
65
+ ```
66
+
67
+ 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.
68
+
69
+ ### Renown in-page sign-in (`connect.renown.switchboardUrl` + `adapters`)
70
+
71
+ 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.
72
+
73
+ `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`.
74
+
75
+ ```jsonc
76
+ "renown": {
77
+ "url": "https://www.renown.id", // redirect fallback
78
+ "switchboardUrl": "https://switchboard.example/graphql", // enables in-page auth
79
+ "adapters": {
80
+ "rainbow": { "walletConnectProjectId": "..." }, // external wallets
81
+ "privy": { "appId": "...", "methods": ["google", "email"] } // social / email
82
+ }
83
+ }
84
+ ```
85
+
86
+ 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.
87
+
88
+ `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`.
89
+
90
+ `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.
91
+
92
+ 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`.
93
+
94
+ ### Reactor enforcement flags (`connect.reactor.featureFlags`)
95
+
96
+ The reactor Connect runs in the browser takes the same four enforcement flags a
97
+ switchboard does: `documentDecisions`, `authEnforcement`, `authGroups`,
98
+ `authConditions`. Each requires the one before it, and the reactor refuses to
99
+ build a set that skips one. All default `false`.
100
+
101
+ ```jsonc
102
+ "reactor": {
103
+ "featureFlags": {
104
+ "documentDecisions": true,
105
+ "authEnforcement": true,
106
+ "authGroups": true,
107
+ "authConditions": true
108
+ }
109
+ }
110
+ ```
111
+
112
+ These are the one part of `connect.*` that is not a local preference. A flag
113
+ changes how stored history is replayed, and a replay verdict is a consensus
114
+ outcome, so **a Connect must carry the same flags as the fleet it syncs with**.
115
+ A flags-off Connect syncing an enforcing switchboard applies operations that
116
+ switchboard denied and the two diverge. Set them per fleet, alongside the
117
+ switchboard's `REACTOR_*` env vars (see `apps/switchboard/README.md`).
118
+
119
+ Both reactor hosts read them: the main-thread reactor takes the value from this
120
+ file directly, and the SharedWorker gets it in its construct message, for the
121
+ same reason it gets `renown.chainId` — a worker has no runtime config of its
122
+ own. There is deliberately no query-param or localStorage override, unlike
123
+ `connect.instance.reactorWorker`: a per-tab flag would be a per-node flag.
124
+
125
+ The flag set is part of the worker's version fingerprint, so a flip is picked up
126
+ even though it isn't a rebuild. A tab whose flags differ from the running
127
+ worker's is told to reload onto a fresh worker, exactly as it would be after a
128
+ new build — without that, the worker would keep enforcing the flags it booted
129
+ with while the tab believed the new set was live. Other tabs still on the old
130
+ worker reload as they refresh.
131
+
132
+ With `authEnforcement` on, both hosts install the Renown trust policy that
133
+ switchboard installs under `REACTOR_AUTH_ENFORCEMENT`: a signed write is
134
+ accepted when a Renown credential binds its key to the wallet it claims, and
135
+ the logged-in user's own key is accepted without a lookup. Credentials are
136
+ read from `connect.renown.switchboardUrl`, or the switchboard `connect.renown.url`
137
+ advertises, else Renown's REST API at `connect.renown.url`, so that endpoint must
138
+ be reachable from the browser. With neither set, the reactor fails to build
139
+ rather than refuse every signed write. The worker gets both URLs in its construct
140
+ message and keeps the ones the first tab booted it with.
141
+
142
+ ### Creation signature policy (`connect.reactor.createSignaturePolicy`)
143
+
144
+ What the documents and drives Connect creates are born as: `"v2-required"`
145
+ (the default) or `"legacy"`. A v2-required document accepts only v2 action
146
+ signatures and takes a content-addressed id. Set `"legacy"` while any reactor
147
+ Connect syncs with predates v2-required documents; existing documents keep
148
+ their policy either way, and the setting does not change what Connect accepts.
149
+
150
+ ```jsonc
151
+ "reactor": { "createSignaturePolicy": "legacy" }
152
+ ```
153
+
154
+ The main-thread reactor reads it from this file; the SharedWorker gets it in its
155
+ construct message and keeps the value the first tab booted it with. It is not
156
+ part of the worker's version fingerprint.
157
+
158
+ ### Stored documents this build does not run (`connect.reactor.unsupportedStoredDocuments`)
159
+
160
+ A reactor refuses to boot when the browser's store holds documents created at a
161
+ protocol version the build does not run, for example after rolling Connect back
162
+ to a release that predates one. Connect then shows "Connect cannot open this
163
+ browser's documents" with the versions and document count, instead of the app.
164
+ There are two ways forward: serve a Connect build that runs those versions, or
165
+ accept them read-only:
166
+
167
+ ```jsonc
168
+ "reactor": { "unsupportedStoredDocuments": "read-only" }
169
+ ```
170
+
171
+ `"refuse"` is the default. With `"read-only"` the reactor boots, logs a warning,
172
+ and refuses every write into those documents and every operation received for
173
+ them; the rest of the store works as usual. Connect has no in-app button for it:
174
+ the setting is the operator's choice, so it goes in this file (or
175
+ `PH_CONNECT_CONFIG_JSON`), and the boot screen's Reload picks up the change.
176
+ Both reactor hosts read it; the SharedWorker gets it in its construct message.
177
+ A worker that refused retries the build on the next tab's connect, so the new
178
+ value takes effect without closing other tabs.
179
+
180
+ ### Multi-reactor routing (`connect.instance.multiReactor`)
181
+
182
+ Experimental, optional, default `false`. When on, Connect reads and writes
183
+ through a router over its own reactor and the Switchboard of the first remote
184
+ default drive (`drives.defaultDrives[].url`), and its reactor gains a local sync
185
+ channel.
186
+
187
+ ```jsonc
188
+ "instance": { "multiReactor": true }
189
+ ```
190
+
191
+ It is part of the worker's version fingerprint, so like the enforcement flags
192
+ it is set in this file only, with no query-param or localStorage override.
193
+
194
+ ## Setting values — the precedence ladder
195
+
196
+ When `ph connect build` runs, the _dist_ `powerhouse.config.json` is produced by deep-merging in this order (lowest → highest):
197
+
198
+ ```
199
+ DEFAULT_CONNECT_CONFIG < source.connect < CLI flag overrides
200
+ ```
201
+
202
+ Plus the top-level field:
203
+
204
+ ```
205
+ packageRegistryUrl = cliPackageRegistryUrl ?? source.packageRegistryUrl ?? null
206
+ ```
207
+
208
+ 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".
209
+
210
+ Two fields interact with the service worker and deserve a caveat:
211
+
212
+ - **`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.
213
+ - **`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.
214
+ - **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.
215
+ - **`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.
216
+
217
+ ### The five ways to feed a value into a layer
218
+
219
+ | Way | Lands in | When to use |
220
+ | ----------------------------------------------------------- | ----------------------------------------------- | -------------------------------------------------------------------- |
221
+ | `ph init` template | source file | Initial scaffold; gives every project a working default |
222
+ | Manual edit of `<project>/powerhouse.config.json` | source file | Local dev tweaks; checked into git |
223
+ | `ph connect config --<field> <value>` (or `--json '{...}'`) | source **and** dist (dual-write) | Quick CLI edit that takes effect on next refresh, without rebuilding |
224
+ | `ph connect build --<field> <value>` (or `--json '{...}'`) | dist (CLI override layer) | One-off override at build time, e.g. CI baking a different `--base` |
225
+ | Docker entrypoint env var `PH_CONNECT_CONFIG_JSON` | dist file at container start, **operator-wins** | Per-deployment knobs without rebuilding the image |
226
+
227
+ Two special-case writers also exist:
228
+
229
+ - `ph install --registry <url>` writes the top-level `packageRegistryUrl` (overwrites when `--registry` is explicit, otherwise preserves existing).
230
+ - `ph vetra` passes a programmatic `callerOverride` to `ph connect studio` so default drives don't have to be tipped on every invocation.
231
+
232
+ ### Notes on each method
233
+
234
+ **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.
235
+
236
+ **`ph connect config`.** Four modes (mutually exclusive — positional, `--get`, `--json`, and field flags cannot be combined):
237
+
238
+ - No args → list mode: prints the effective `connect.*` block (defaults + source).
239
+ - `<key>` (positional) or `--get <dotted.path>` → prints a single value at the dotted path (also works for top-level `packageRegistryUrl`).
240
+ - `<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.
241
+ - `--json '{...}'` → bulk-set mode: validates the full patch and dual-writes.
242
+
243
+ **`--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.
244
+
245
+ ```bash
246
+ # Enables workflows and adds a default drive.
247
+ ph connect build --json '{"app":{"workflowsEnabled":true},"drives":{"defaultDrives":[{"url":"http://localhost:4001/d/my-workflows","name":"My workflows"}]}}'
248
+ ```
249
+
250
+ **`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>`.
251
+
252
+ **`--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`.
253
+
254
+ **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.
255
+
256
+ ```bash
257
+ docker run \
258
+ -e PH_CONNECT_CONFIG_JSON='{"connect":{"renown":{"url":"https://renown.staging"},"app":{"logLevel":"debug"}}}' \
259
+ connect:latest
260
+ ```
261
+
262
+ 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.
263
+
264
+ ## How Connect reads the file at boot
265
+
266
+ `apps/connect/main.tsx`:
267
+
268
+ ```tsx
269
+ import { createRoot } from "react-dom/client";
270
+ import { loadRuntimeConfig } from "./src/runtime-config.js";
271
+
272
+ if (!window.ph) window.ph = {};
273
+
274
+ // Bootstrap the runtime config BEFORE AppLoader's transitive imports
275
+ await loadRuntimeConfig();
276
+ const { AppLoader } = await import("./src/components/app-loader.js");
277
+
278
+ createRoot(document.getElementById("root")!).render(<AppLoader />);
279
+ ```
280
+
281
+ Two ordering tricks:
282
+
283
+ 1. **Top-level await** on `loadRuntimeConfig()` blocks module evaluation until the fetch resolves.
284
+ 2. **Dynamic import** of `AppLoader` so any module that calls `getRuntimeConfig()` at import time (synchronous read from the cache) only runs _after_ step 1.
285
+
286
+ Together these prevent a cache-empty race where the SPA would have to fall back to defaults or throw.
287
+
288
+ `loadRuntimeConfig` (in `apps/connect/src/runtime-config.ts`) is a 4-line wrapper around the shared loader:
289
+
290
+ ```ts
291
+ const loader = new ConfigLoader(
292
+ new JsonConfigAdapter({
293
+ path: `${import.meta.env.BASE_URL}powerhouse.config.json`,
294
+ }),
295
+ );
296
+ ```
297
+
298
+ - `ConfigLoader` (in `packages/shared/connect/config-loader.ts`) wraps any `ConfigAdapter` with deep-merge-against-defaults and in-process caching.
299
+ - `JsonConfigAdapter` reads via `fetch()` when `window` is defined, via `fs` in Node.
300
+ - After `loadRuntimeConfig()` resolves once, any synchronous `getRuntimeConfig()` call returns the cached payload immediately.
301
+
302
+ Downstream consumers inside the SPA:
303
+
304
+ | File | Reads |
305
+ | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
306
+ | `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 |
307
+ | `apps/connect/src/hooks/useRegistryPackages.ts` | `getRuntimeConfig().packageRegistryUrl` |
308
+ | `apps/connect/src/store/reactor.ts` | Passes `packageRegistryUrl` to `BrowserPackageManager`; reads `connect.reactor.featureFlags`, `createSignaturePolicy` and `unsupportedStoredDocuments` for both reactor hosts |
309
+ | Renown auth flow | Reads `connect.renown.*` |
310
+ | Drives sidebar | Reads `connect.drives.*` |
311
+ | Router | Reads `connect.app.basePath` |
312
+ | `apps/connect/src/components/app.tsx` | Reads `connect.app.offline` to register or unregister the service worker |
313
+
314
+ 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.
315
+
316
+ ## Other consumers of the same file
317
+
318
+ The dist `powerhouse.config.json` is not a Connect-private artefact:
319
+
320
+ - **Switchboard** (Node) reads `packages[]` and `packageRegistryUrl` at startup via the same `ConfigLoader` + `JsonConfigAdapter` (Node branch).
321
+ - **`ph install` / `ph publish`** use `resolveRegistryUrl` to pick a registry with priority `--flag > PH_REGISTRY_URL env > config.packageRegistryUrl > DEFAULT_REGISTRY_URL`.
322
+
323
+ This is why `packageRegistryUrl` lives at the top level rather than nested under `connect.*` — it's a project-wide setting, not Connect-only.
324
+
325
+ ## Common operator workflows
326
+
327
+ **"I just want to point Connect at a different registry."**
328
+ Edit the project's `powerhouse.config.json`, set `"packageRegistryUrl": "https://my.registry"`, refresh Connect. Or `ph connect config --packages-registry https://my.registry`.
329
+
330
+ **"I want a subpath deploy (`/connect` instead of `/`)."**
331
+ `ph connect build --base /connect`. The CLI override lands in the dist `connect.app.basePath` and the bundled assets pick it up.
332
+
333
+ **"I want default drives to load automatically."**
334
+ `ph connect config --default-drives-url https://drive-a, https://drive-b`. The CSV is parsed into `connect.drives.defaultDrives[]` objects.
335
+
336
+ **"I want my project to boot with a preconfigured local drive."**
337
+ Add a local entry to `connect.drives.defaultDrives` in `powerhouse.config.json`:
338
+ `{"local": true, "id": "my-drive", "name": "My Drive", "icon": "https://…", "app": "powerhouse/generic-drive-explorer"}`.
339
+ 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.
340
+
341
+ **"I'm deploying the docker image to a new environment and need to override renown."**
342
+ 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.
343
+
344
+ **"I need a different Sentry DSN per environment."**
345
+ 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:
346
+
347
+ ```bash
348
+ docker run -e PH_CONNECT_CONFIG_JSON='{
349
+ "connect": {
350
+ "sentry": { "dsn": "https://prod-key@sentry.io/1", "env": "prod", "tracing": true }
351
+ }
352
+ }' connect:latest
353
+ ```
354
+
355
+ `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.
356
+
357
+ **"I want OpenPanel analytics on this deployment."**
358
+ Set `connect.openPanel.clientId` (and `apiUrl` for a self-hosted OpenPanel):
359
+
360
+ ```bash
361
+ docker run -e PH_CONNECT_CONFIG_JSON='{
362
+ "connect": {
363
+ "openPanel": { "clientId": "<client-id>", "apiUrl": "https://openpanel.example/api" }
364
+ }
365
+ }' connect:latest
366
+ ```
367
+
368
+ 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.
369
+
370
+ **"I'm turning auth enforcement on for this fleet."**
371
+ Set the whole flag set on the container, matching the switchboard's `REACTOR_*` env vars exactly:
372
+
373
+ ```bash
374
+ docker run -e PH_CONNECT_CONFIG_JSON='{
375
+ "connect": {
376
+ "reactor": { "featureFlags": {
377
+ "documentDecisions": true, "authEnforcement": true,
378
+ "authGroups": true, "authConditions": true
379
+ } }
380
+ }
381
+ }' connect:latest
382
+ ```
383
+
384
+ 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").
385
+
386
+ **"I want to verify what Connect will actually use without booting it."**
387
+ `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.
388
+
389
+ ## Adding or changing a config field (developers)
390
+
391
+ A `connect.*` field is declared once, in zod; everything else is derived from
392
+ it. The `PHConnect*` TS types are `z.infer` of the schemas, the JSON Schema
393
+ fragment Ajv uses (`phConnectRuntimeConfigSchema`) is emitted from them, and
394
+ the two committed `*.schema.json` files are generated from that fragment.
395
+
396
+ 1. **Schema** — `packages/shared/connect/connect-config-schema.ts`. Declare the
397
+ field in the relevant `connect*Schema` section (e.g. `connectPackagesSchema`),
398
+ with its description and `default` in `.meta({ description, default })`.
399
+ Never use `.default(x)` (it fills values on parse) or `.meta({ id })` (it
400
+ emits `$defs`). The matching `PHConnect*` type in
401
+ `packages/shared/clis/types.ts` picks the field up through `z.infer`, and the
402
+ emitted fragment in `packages/shared/connect/schema-fragments.ts` through
403
+ `z.toJSONSchema`; neither is edited by hand. The drift test
404
+ `connect-config-schema.test.ts` pins the emitted fragment: update its
405
+ snapshot (`vitest -u`) after reviewing the diff.
406
+ 2. **Default** — `packages/shared/connect/runtime-config.ts`. Add the field's
407
+ default to `DEFAULT_CONNECT_CONFIG` so the SPA never sees it undefined.
408
+ 3. **Rebuild** the source-of-truth packages so the emit script sees the change:
409
+ ```bash
410
+ pnpm --filter=@powerhousedao/shared --filter=@powerhousedao/builder-tools build
411
+ ```
412
+ 4. **Regenerate** the committed JSON schemas:
413
+ ```bash
414
+ pnpm tsx scripts/emit-schemas.ts
415
+ ```
416
+ This rewrites `packages/builder-tools/connect-utils/runtime-config.schema.json`
417
+ and `packages/shared/clis/source-config.schema.json`. Commit both.
418
+
419
+ **`connect.pwa.*` fields have a second, hand-kept zod schema.** `PwaConfigSchema` /
420
+ `PwaManifestOverrideSchema` in `packages/shared/document-model/schemas.ts` is
421
+ the validator `ph connect build` actually runs against `connect.pwa` (via
422
+ `validateProjectPwaConfig`), and it is hand-maintained: `emit-schemas.ts` does
423
+ not regenerate it, and the coverage test below does not cover it (there is no
424
+ `pwa` default). It mirrors `connectPwaSchema`; its `z.ZodType<PHConnectPwa>`
425
+ annotation pins it to the inferred type, but does not force it to gain a
426
+ newly-added optional field. So when you add a `connect.pwa.*` field, declare it there too —
427
+ the objects are strict (`z.strictObject`), so a field the schema doesn't know
428
+ fails the build as an unrecognized key rather than being silently dropped.
429
+
430
+ Then consume it in the SPA via `getRuntimeConfig().connect?.<block>?.<field>`
431
+ (or add a typed accessor in `apps/connect/src/connect.config.ts`).
432
+
433
+ Optional, depending on the field:
434
+
435
+ - **CLI flag** — to expose `ph connect config/build --<field>`, wire it through
436
+ `packages/shared/clis/args/connect.ts` and `clis/ph-cli/src/utils/cli-connect-override.ts`
437
+ (see `externalEnabled` → `--external-packages` for the pattern).
438
+ - **Scaffold default** — if new projects should ship the field, add it to the
439
+ `ph init` template at `packages/codegen/src/templates/boilerplate/powerhouse.config.json.ts`.
440
+
441
+ The `runtime-config-schema.test.ts` coverage test asserts every key emitted from
442
+ `DEFAULT_CONNECT_CONFIG` has a matching schema declaration — it fails loudly if
443
+ you add a default (step 2) but skip the schema (step 1).
444
+
445
+ ## Reference: key files
446
+
447
+ ```
448
+ packages/shared/connect/
449
+ ├ connect-config-schema.ts zod schemas: the single source of connect.* fields
450
+ ├ schema-fragments.ts JSON Schema fragments emitted from the zod schemas
451
+ ├ runtime-config.ts DEFAULT_CONNECT_CONFIG, types, buildRuntimeConfig
452
+ ├ config-loader.ts ConfigLoader, ConfigAdapter, deepMerge
453
+ └ json-adapter.ts JsonConfigAdapter (browser fetch | Node fs)
454
+
455
+ packages/builder-tools/connect-utils/
456
+ ├ runtime-config-schema.ts JSON Schema (Ajv), composed from the emitted fragment
457
+ └ vite-plugins/ph-config.ts Emits dist file & serves /powerhouse.config.json in dev
458
+
459
+ clis/ph-cli/src/
460
+ ├ utils/cli-connect-override.ts buildConnectFlagPatch, wasFlagExplicitlyPassed, buildCliConnectOverride
461
+ ├ utils/connect-config-validation.ts validateConnectPatch (Ajv)
462
+ ├ services/connect-config.ts `ph connect config` handler
463
+ ├ services/connect-studio.ts `ph connect studio` (accepts callerOverride)
464
+ ├ services/vetra.ts `ph vetra` (constructs callerOverride)
465
+ ├ commands/install.ts `ph install` (writes packageRegistryUrl)
466
+ └ utils.ts updateConfigFile
467
+
468
+ apps/connect/
469
+ ├ main.tsx top-level await + dynamic import (boot race fix)
470
+ └ src/runtime-config.ts loadRuntimeConfig, getRuntimeConfig
471
+
472
+ packages/codegen/src/templates/boilerplate/powerhouse.config.json.ts
473
+ └ `ph init` boilerplate template
474
+
475
+ docker/connect-entrypoint.sh
476
+ └ PH_CONNECT_CONFIG_JSON → dist overrides (jq deep-merge, operator-wins)
477
+ ```
478
+
479
+ ## Design principle, in one line
480
+
481
+ 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).