@powerhousedao/connect 6.2.3-dev.66 → 6.2.3-dev.68

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 (248) hide show
  1. package/CUSTOMIZING.md +77 -0
  2. package/README.md +18 -91
  3. package/RUNTIME-CONFIG.md +472 -0
  4. package/dist/{AddDriveModal-D_3jDwjp.js → AddDriveModal-BjgmiHJr.js} +6 -6
  5. package/dist/AddDriveModal-BjgmiHJr.js.map +1 -0
  6. package/dist/{ClearStorageModal-zZ8XzwmR.js → ClearStorageModal-Dm8fXUtB.js} +6 -6
  7. package/dist/ClearStorageModal-Dm8fXUtB.js.map +1 -0
  8. package/dist/{ConfirmDocumentUpgradeModal-CrU2Z1CL.js → ConfirmDocumentUpgradeModal-CoixS60F.js} +5 -5
  9. package/dist/ConfirmDocumentUpgradeModal-CoixS60F.js.map +1 -0
  10. package/dist/{CookiesPolicyModal-DQwsgDI9.js → CookiesPolicyModal-BpFjYc7T.js} +4 -4
  11. package/dist/{CookiesPolicyModal-DQwsgDI9.js.map → CookiesPolicyModal-BpFjYc7T.js.map} +1 -1
  12. package/dist/{CreateDocumentModal-Cf1APibL.js → CreateDocumentModal-B-cXzeOA.js} +10 -10
  13. package/dist/CreateDocumentModal-B-cXzeOA.js.map +1 -0
  14. package/dist/{DebugSettingsModal-DIc5C2lI.js → DebugSettingsModal-D2n1zf1j.js} +8 -8
  15. package/dist/DebugSettingsModal-D2n1zf1j.js.map +1 -0
  16. package/dist/{DeleteDriveModal-lE9eCBua.js → DeleteDriveModal-1pAIayG_.js} +5 -5
  17. package/dist/DeleteDriveModal-1pAIayG_.js.map +1 -0
  18. package/dist/{DeleteItemModal-BFgcGsm3.js → DeleteItemModal-BUpqmFxS.js} +5 -5
  19. package/dist/DeleteItemModal-BUpqmFxS.js.map +1 -0
  20. package/dist/{DisclaimerModal-CF6JkIIu.js → DisclaimerModal-TIJXRYLF.js} +5 -5
  21. package/dist/DisclaimerModal-TIJXRYLF.js.map +1 -0
  22. package/dist/{DocumentVersionUnsupportedModal-Cm9Jb9W7.js → DocumentVersionUnsupportedModal-DH9Zzsyw.js} +5 -5
  23. package/dist/DocumentVersionUnsupportedModal-DH9Zzsyw.js.map +1 -0
  24. package/dist/{DownloadDocumentWithErrorsModal-CShKhfEQ.js → DownloadDocumentWithErrorsModal-Beh-xw8B.js} +5 -5
  25. package/dist/DownloadDocumentWithErrorsModal-Beh-xw8B.js.map +1 -0
  26. package/dist/{DriveAuthRequiredModal-CMwPUyZf.js → DriveAuthRequiredModal-XTcoJKvj.js} +6 -6
  27. package/dist/DriveAuthRequiredModal-XTcoJKvj.js.map +1 -0
  28. package/dist/{DriveSettingsModal-BSImj4BH.js → DriveSettingsModal-DZKawN7w.js} +5 -5
  29. package/dist/DriveSettingsModal-DZKawN7w.js.map +1 -0
  30. package/dist/{InspectorModal-Dr8-gj6u.js → InspectorModal-Zuv-MhXn.js} +16 -16
  31. package/dist/InspectorModal-Zuv-MhXn.js.map +1 -0
  32. package/dist/{LoginModal-DT_05uva.js → LoginModal-O06ZvWFI.js} +6 -6
  33. package/dist/LoginModal-O06ZvWFI.js.map +1 -0
  34. package/dist/{OpenFileDocumentsModal-X9GnX2Bk.js → OpenFileDocumentsModal-BNHD0vg9.js} +6 -6
  35. package/dist/OpenFileDocumentsModal-BNHD0vg9.js.map +1 -0
  36. package/dist/{UpgradeDriveModal-DvM-PNWe.js → UpgradeDriveModal-CCWKp5yn.js} +5 -5
  37. package/dist/UpgradeDriveModal-CCWKp5yn.js.map +1 -0
  38. package/dist/app-loader-DDh_8DF4.js +4 -0
  39. package/dist/{app-loader-DrViXipO.js → app-loader-Jc7RPPdf.js} +149 -196
  40. package/dist/app-loader-Jc7RPPdf.js.map +1 -0
  41. package/dist/{app-skeleton-gzg8cRzm.js → app-skeleton-BFjvlTWd.js} +11 -11
  42. package/dist/app-skeleton-BFjvlTWd.js.map +1 -0
  43. package/dist/{app-skeleton-DYLZ7npI.js → app-skeleton-DFg65Rxa.js} +3 -3
  44. package/dist/{boot-CC_DgQKX.js → boot-CvNYaPVX.js} +6 -6
  45. package/dist/boot-CvNYaPVX.js.map +1 -0
  46. package/dist/{build-info-DMrToXJe.js → build-info-D1EoCSh4.js} +5 -5
  47. package/dist/{build-info-DMrToXJe.js.map → build-info-D1EoCSh4.js.map} +1 -1
  48. package/dist/{components-CjF9XjxP.js → components-B1iKyGVL.js} +11 -10
  49. package/dist/{components-CjF9XjxP.js.map → components-B1iKyGVL.js.map} +1 -1
  50. package/dist/{connect.config-uZF-gnvV.js → connect.config-D1pGNmaF.js} +4 -4
  51. package/dist/connect.config-D1pGNmaF.js.map +1 -0
  52. package/dist/{connection-state-C_477Kr_.js → connection-state-B6fleM37.js} +6 -6
  53. package/dist/connection-state-B6fleM37.js.map +1 -0
  54. package/dist/{cookie-banner-HPgyuHM5.js → cookie-banner-CAvd3PC3.js} +6 -6
  55. package/dist/{cookie-banner-HPgyuHM5.js.map → cookie-banner-CAvd3PC3.js.map} +1 -1
  56. package/dist/document-editor-container-BnEjlmaN.js +307 -0
  57. package/dist/document-editor-container-BnEjlmaN.js.map +1 -0
  58. package/dist/document-editor-container-kgS38mkb.js +4 -0
  59. package/dist/error-boundary-BsUBww61.js +155 -0
  60. package/dist/error-boundary-BsUBww61.js.map +1 -0
  61. package/dist/generic.d.ts +116 -0
  62. package/dist/generic.d.ts.map +1 -0
  63. package/dist/generic.js +31 -0
  64. package/dist/generic.js.map +1 -0
  65. package/dist/{i18n-CTgT1HG-.js → i18n-D9WYPgk9.js} +4 -4
  66. package/dist/{i18n-CTgT1HG-.js.map → i18n-D9WYPgk9.js.map} +1 -1
  67. package/dist/index-B4g8swZG.d.ts +4 -0
  68. package/dist/layout-BOX6fL5v.js +5 -0
  69. package/dist/layout.d.ts +2 -28
  70. package/dist/layout.js +4 -6
  71. package/dist/load-runtime-config-DBnKV0Lk.js +14 -0
  72. package/dist/load-runtime-config-DBnKV0Lk.js.map +1 -0
  73. package/dist/{load--K_UgzUy.js → load-v3HkhMUC.js} +11 -11
  74. package/dist/{load--K_UgzUy.js.map → load-v3HkhMUC.js.map} +1 -1
  75. package/dist/main.js +2 -2
  76. package/dist/{open-file-uploads-BcyWmUZn.js → open-file-uploads-B5pr1sA2.js} +4 -4
  77. package/dist/{open-file-uploads-BcyWmUZn.js.map → open-file-uploads-B5pr1sA2.js.map} +1 -1
  78. package/dist/{package-manager-BkFRzovd.js → package-manager-x_fK8Hzm.js} +92 -60
  79. package/dist/package-manager-x_fK8Hzm.js.map +1 -0
  80. package/dist/{pglite-seed-BsEPByVM.js → pglite-seed-eGzXMld2.js} +4 -4
  81. package/dist/{pglite-seed-BsEPByVM.js.map → pglite-seed-eGzXMld2.js.map} +1 -1
  82. package/dist/{plugin-host--lBWChr9.js → plugins--nrQ3PK_.js} +75 -83
  83. package/dist/plugins--nrQ3PK_.js.map +1 -0
  84. package/dist/{preferences-store-DANUajdg.js → preferences-store-CSqauT9V.js} +5 -5
  85. package/dist/preferences-store-CSqauT9V.js.map +1 -0
  86. package/dist/prerender.d.ts +38 -0
  87. package/dist/prerender.d.ts.map +1 -0
  88. package/dist/prerender.js +177 -0
  89. package/dist/prerender.js.map +1 -0
  90. package/dist/{prerendered-shell-DxCUDEXL.js → prerendered-shell-peKE7AqI.js} +10 -4
  91. package/dist/prerendered-shell-peKE7AqI.js.map +1 -0
  92. package/dist/{reactor-5nod7BfF.js → reactor-CiqT6V1j.js} +25 -156
  93. package/dist/reactor-CiqT6V1j.js.map +1 -0
  94. package/dist/{registerServiceWorker-CkVxA2KC.js → registerServiceWorker-APlHkrmH.js} +4 -4
  95. package/dist/{registerServiceWorker-CkVxA2KC.js.map → registerServiceWorker-APlHkrmH.js.map} +1 -1
  96. package/dist/root-B1Pq9x6S.js +24 -0
  97. package/dist/root-B1Pq9x6S.js.map +1 -0
  98. package/dist/route-tree.d.ts +147 -156
  99. package/dist/route-tree.d.ts.map +1 -1
  100. package/dist/route-tree.js +93 -169
  101. package/dist/route-tree.js.map +1 -1
  102. package/dist/route-views-BF0p-4Fi.js +60 -0
  103. package/dist/route-views-BF0p-4Fi.js.map +1 -0
  104. package/dist/route-views-CTARvT5N.js +55 -0
  105. package/dist/route-views-CTARvT5N.js.map +1 -0
  106. package/dist/route-views-D8I-1PWU.js +4 -0
  107. package/dist/route-views.d.ts +7 -0
  108. package/dist/route-views.d.ts.map +1 -0
  109. package/dist/route-views.js +4 -0
  110. package/dist/router-BguOMBUh.js +4 -0
  111. package/dist/router-L9X9U-97.js +46 -0
  112. package/dist/router-L9X9U-97.js.map +1 -0
  113. package/dist/router.d.ts +1 -3
  114. package/dist/router.js +3 -7
  115. package/dist/sentry-Cuc_Nbba.js +22 -0
  116. package/dist/sentry-Cuc_Nbba.js.map +1 -0
  117. package/dist/{settings-DkLhRfEI.js → settings-gMoXPPnn.js} +488 -22
  118. package/dist/settings-gMoXPPnn.js.map +1 -0
  119. package/dist/settings-tabs-DBwSlWx8.js +365 -0
  120. package/dist/settings-tabs-DBwSlWx8.js.map +1 -0
  121. package/dist/shell-core-head.html +2 -0
  122. package/dist/shell-core.html +1 -0
  123. package/dist/shell-head.html +2 -1
  124. package/dist/shell-plugins.json +1 -0
  125. package/dist/shell.html +1 -1
  126. package/dist/start-connect.d.ts +5 -9
  127. package/dist/start-connect.d.ts.map +1 -1
  128. package/dist/start-connect.js +5 -6
  129. package/dist/start-connect.js.map +1 -1
  130. package/dist/style.css +3127 -4014
  131. package/dist/ui-g3mVHWI7.js +66 -0
  132. package/dist/ui-g3mVHWI7.js.map +1 -0
  133. package/dist/{use-renown-login-BzOSQETV.js → use-renown-login-dPpDOYq5.js} +4 -4
  134. package/dist/use-renown-login-dPpDOYq5.js.map +1 -0
  135. package/docs/customizing/data-and-navigation.md +177 -0
  136. package/docs/customizing/hosts-and-plugins.md +65 -0
  137. package/docs/customizing/layout.md +149 -0
  138. package/docs/customizing/modals.md +78 -0
  139. package/docs/customizing/overrides.md +113 -0
  140. package/docs/customizing/packages.md +38 -0
  141. package/docs/customizing/pages.md +136 -0
  142. package/docs/customizing/styles-and-branding.md +41 -0
  143. package/docs/customizing/types-and-troubleshooting.md +44 -0
  144. package/package.json +41 -18
  145. package/scripts/prerender-shell.ts +35 -84
  146. package/skills/customize-connect/SKILL.md +74 -0
  147. package/src/route-tree.ts +3 -0
  148. package/src/routeTree.gen.ts +134 -192
  149. package/src/router/index.ts +2 -51
  150. package/src/router/register.ts +1 -1
  151. package/src/routes/__root.tsx +8 -24
  152. package/src/routes/_app/$.tsx +13 -0
  153. package/src/routes/_app/d/$driveSlug/{-$nodeSlug}.tsx +13 -0
  154. package/src/routes/_app/d/$driveSlug.tsx +13 -0
  155. package/src/routes/_app/index.tsx +13 -0
  156. package/src/routes/_app/settings/appearance.tsx +13 -0
  157. package/src/routes/_app/settings/packages.tsx +13 -0
  158. package/src/routes/_app/settings.tsx +13 -0
  159. package/src/routes/_app.tsx +13 -0
  160. package/style.css +5 -22
  161. package/tailwind.css +12 -0
  162. package/dist/AddDriveModal-D_3jDwjp.js.map +0 -1
  163. package/dist/ClearStorageModal-zZ8XzwmR.js.map +0 -1
  164. package/dist/ConfirmDocumentUpgradeModal-CrU2Z1CL.js.map +0 -1
  165. package/dist/CreateDocumentModal-Cf1APibL.js.map +0 -1
  166. package/dist/DebugSettingsModal-DIc5C2lI.js.map +0 -1
  167. package/dist/DeleteDriveModal-lE9eCBua.js.map +0 -1
  168. package/dist/DeleteItemModal-BFgcGsm3.js.map +0 -1
  169. package/dist/DisclaimerModal-CF6JkIIu.js.map +0 -1
  170. package/dist/DocumentVersionUnsupportedModal-Cm9Jb9W7.js.map +0 -1
  171. package/dist/DownloadDocumentWithErrorsModal-CShKhfEQ.js.map +0 -1
  172. package/dist/DriveAuthRequiredModal-CMwPUyZf.js.map +0 -1
  173. package/dist/DriveSettingsModal-BSImj4BH.js.map +0 -1
  174. package/dist/InspectorModal-Dr8-gj6u.js.map +0 -1
  175. package/dist/LoginModal-DT_05uva.js.map +0 -1
  176. package/dist/MissingPackageModal-DtISKgub.js +0 -49
  177. package/dist/MissingPackageModal-DtISKgub.js.map +0 -1
  178. package/dist/OpenFileDocumentsModal-X9GnX2Bk.js.map +0 -1
  179. package/dist/UpgradeDriveModal-DvM-PNWe.js.map +0 -1
  180. package/dist/app-layout-BIq-ZW-6.js +0 -394
  181. package/dist/app-layout-BIq-ZW-6.js.map +0 -1
  182. package/dist/app-loader-CWAH-WxW.js +0 -4
  183. package/dist/app-loader-DrViXipO.js.map +0 -1
  184. package/dist/app-skeleton-gzg8cRzm.js.map +0 -1
  185. package/dist/boot-CC_DgQKX.js.map +0 -1
  186. package/dist/connect-router-KmNBGS0G.js +0 -434
  187. package/dist/connect-router-KmNBGS0G.js.map +0 -1
  188. package/dist/connect.config-uZF-gnvV.js.map +0 -1
  189. package/dist/connection-state-C_477Kr_.js.map +0 -1
  190. package/dist/index-UrZFqSgm.d.ts +0 -166
  191. package/dist/index-UrZFqSgm.d.ts.map +0 -1
  192. package/dist/layout.d.ts.map +0 -1
  193. package/dist/multi-reactor-fSKpLBjT.js +0 -220
  194. package/dist/multi-reactor-fSKpLBjT.js.map +0 -1
  195. package/dist/package-manager-BkFRzovd.js.map +0 -1
  196. package/dist/plugin-host--lBWChr9.js.map +0 -1
  197. package/dist/preferences-store-DANUajdg.js.map +0 -1
  198. package/dist/prerendered-shell-DxCUDEXL.js.map +0 -1
  199. package/dist/reactor-5nod7BfF.js.map +0 -1
  200. package/dist/route-components-BkztQruF.js +0 -148
  201. package/dist/route-components-BkztQruF.js.map +0 -1
  202. package/dist/router-8RIbbf6v.js +0 -4
  203. package/dist/router-C37yATTD.js +0 -604
  204. package/dist/router-C37yATTD.js.map +0 -1
  205. package/dist/runtime-config-DdN1Frg7.js +0 -34
  206. package/dist/runtime-config-DdN1Frg7.js.map +0 -1
  207. package/dist/runtime-flag-B8IYhkz-.js +0 -4
  208. package/dist/runtime-flag-CT5OKujT.js +0 -45
  209. package/dist/runtime-flag-CT5OKujT.js.map +0 -1
  210. package/dist/sentry-CJb7--mu.js +0 -18
  211. package/dist/sentry-CJb7--mu.js.map +0 -1
  212. package/dist/settings-CjvK8OKA.js +0 -91
  213. package/dist/settings-CjvK8OKA.js.map +0 -1
  214. package/dist/settings-DkLhRfEI.js.map +0 -1
  215. package/dist/sidebar-BXf8OEwm.d.ts +0 -34
  216. package/dist/sidebar-BXf8OEwm.d.ts.map +0 -1
  217. package/dist/sidebar-lAVFRsni.js +0 -31
  218. package/dist/sidebar-lAVFRsni.js.map +0 -1
  219. package/dist/use-renown-login-BzOSQETV.js.map +0 -1
  220. package/dist/useIsEmbedded-BWJ0qb7w.js +0 -26
  221. package/dist/useIsEmbedded-BWJ0qb7w.js.map +0 -1
  222. package/dist/useRegistryPackages-BqIWwXV-.js +0 -452
  223. package/dist/useRegistryPackages-BqIWwXV-.js.map +0 -1
  224. package/scripts/critical-css.ts +0 -243
  225. package/src/router/connect-router.ts +0 -170
  226. package/src/router/drive-route-loader.ts +0 -116
  227. package/src/router/navigation.ts +0 -230
  228. package/src/router/perf-marks.test.tsx +0 -98
  229. package/src/router/perf-marks.ts +0 -97
  230. package/src/router/route-components.tsx +0 -98
  231. package/src/router/route-tree.ts +0 -88
  232. package/src/router/scroll.ts +0 -69
  233. package/src/router/search.ts +0 -66
  234. package/src/router/settings.ts +0 -120
  235. package/src/router/sidebar.ts +0 -55
  236. package/src/router/titles.test.ts +0 -24
  237. package/src/router/titles.ts +0 -33
  238. package/src/routes/core/_app/$.tsx +0 -13
  239. package/src/routes/core/_app/_content/d/$driveSlug/{-$nodeSlug}.tsx +0 -52
  240. package/src/routes/core/_app/_content/index.tsx +0 -3
  241. package/src/routes/core/_app/_content.tsx +0 -9
  242. package/src/routes/core/_app/settings/about.tsx +0 -20
  243. package/src/routes/core/_app/settings/ai-assistant.tsx +0 -20
  244. package/src/routes/core/_app/settings/danger-zone.tsx +0 -21
  245. package/src/routes/core/_app/settings/default-editors.tsx +0 -20
  246. package/src/routes/core/_app/settings/package-manager.tsx +0 -20
  247. package/src/routes/core/_app/settings.tsx +0 -35
  248. package/src/routes/core/_app.tsx +0 -10
package/CUSTOMIZING.md ADDED
@@ -0,0 +1,77 @@
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, 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/src/prerender/shell-css.ts` | The loading screen's CSS, built by Tailwind's compiler. |
76
+ | `packages/reactor-browser/src/hooks/navigation.ts`, `link-props.ts` | The navigation API for editors. |
77
+ | `test/versioned-documents/hosts/connect/routes/` | A working example project. |
package/README.md CHANGED
@@ -64,104 +64,31 @@ Connect's runtime settings (renown URL, package registry, default drives, log le
64
64
 
65
65
  ## Routes
66
66
 
67
- Connect routes with [TanStack Router](https://tanstack.com/router) file routes. Its own routes live in `src/routes`: the root route (`__root.tsx`: global search params, titles, the not-found default), the pathless `_app` layout (`core/_app.tsx`: the sidebar) and the core routes inside it in `src/routes/core/_app` (`/`, `/d/$driveSlug/{-$nodeSlug}`, `/settings/*` and the 404 catch-all `$`). `src/routeTree.gen.ts` is generated from them (`pnpm exec tsr generate`, or `vite dev`) and committed.
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
68
 
69
- For a task-by-task guide to customizing Connect from a project (pages, sidebar links, layouts, settings tabs, data, titles, navigation), see [CUSTOMIZING.md](./CUSTOMIZING.md).
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
70
 
71
- ### Adding routes to a deployment
72
-
73
- A project built with `ph connect build` (or served by `ph connect studio`/`preview`, or `ph run connect`) adds routes by placing file routes in `hosts/connect/routes/`. A plain `ph build` reads the same folder.
74
-
75
- ```tsx
76
- // hosts/connect/routes/hello.tsx
77
- import { createFileRoute } from "@tanstack/react-router";
78
-
79
- export const Route = createFileRoute("/hello")({
80
- // The router context carries the app's PH store.
81
- loader: ({ context }) => ({ driveCount: context.store.drives?.length ?? 0 }),
82
- component: Hello,
83
- });
84
71
  ```
85
-
86
- - The build mounts the routes folder under Connect's root route (global search params and titles included) and code-splits each route.
87
- - The route tree is generated into `.ph/connect-routes.gen.ts`, which also registers the router type, so `Link` and `navigate` are typed with the project's routes. To type-check route files, the tsconfig includes `.ph/connect-routes.gen.ts` and maps `"@powerhousedao/connect/route-tree": ["./.ph/connect-routes.gen.ts"]` in `paths`; new projects are scaffolded with both, and older ones add them by hand (drop `.ph` from `exclude` too, or it filters the file out). Until a build generates the tree, the import falls back to Connect's core tree. `ph build` generates it before it runs tsc.
88
- - A route whose full path equals a core route's (e.g. `index.tsx` for `/`) fails the build. Core routes cannot be overridden.
89
- - The project needs `@tanstack/react-router` as a dependency, in the version Connect uses.
90
- - Without a routes folder, no router plugin runs and Connect uses its prebuilt route tree.
91
-
92
- ### Layouts and the sidebar
93
-
94
- Where a file sits decides whether its page has Connect's sidebar:
95
-
96
- - `_app/<x>.tsx` renders inside Connect's `_app` layout, with the sidebar. Its id starts with `/_app`, e.g. `createFileRoute("/_app/reports")`; the URL is `/reports`.
97
- - Any other file, e.g. `hello.tsx`, renders full-page, without the sidebar.
98
- - Route groups, `(name)/`, only organise files.
99
-
100
- A route adds itself to the sidebar with `staticData.nav`, and changes the sidebar for its page (and its children) with `staticData.sidebar`:
101
-
102
- ```tsx
103
- // hosts/connect/routes/_app/reports.tsx
104
- export const Route = createFileRoute("/_app/reports")({
105
- // Listed after the drives, by order; routes with path params are not listed.
106
- staticData: { nav: { label: "Reports", order: 10, icon: FileText } },
107
- component: Reports,
108
- });
109
-
110
- // hosts/connect/routes/_app/focus.tsx
111
- export const Route = createFileRoute("/_app/focus")({
112
- // "hidden" drops the sidebar; "collapsed" keeps only its header and footer.
113
- staticData: { sidebar: "hidden" },
114
- component: Focus,
115
- });
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
116
80
  ```
117
81
 
118
- A project's `_app.tsx` replaces Connect's layout: Connect's core routes and the project's `_app/` routes then render inside it. `@powerhousedao/connect/layout` exports the parts to compose one: `AppLayout` (the default, with a `sidebar` prop), `ConnectSidebar` (with `extraItems` and `collapsed`), `SidebarDriveItems`, `SidebarNavItems`, `SidebarItem`, `useNavRoutes` and `useSidebarMode`.
119
-
120
- ```tsx
121
- // hosts/connect/routes/_app.tsx
122
- import { AppLayout, ConnectSidebar, SidebarItem } from "@powerhousedao/connect/layout";
123
- import { createFileRoute } from "@tanstack/react-router";
124
-
125
- export const Route = createFileRoute("/_app")({
126
- component: () => (
127
- <AppLayout
128
- sidebar={<ConnectSidebar extraItems={<SidebarItem title="Docs" href="https://docs.example" />} />}
129
- />
130
- ),
131
- });
132
- ```
133
-
134
- The prerendered loading shell in `index.html` always shows Connect's sidebar. With a replaced layout, or on a full-page route, the page swaps to its own layout once the app renders.
135
-
136
- ### Not found
137
-
138
- - An unknown path matches the catch-all `core/_app/$.tsx`, so its 404 page renders inside the `_app` layout, with the sidebar. The page shows the requested path and a link home; the title is `Not found · <app>`. The URL stays as typed.
139
- - A drive that is not listed once drive arrivals settle shows the same page, "Drive `<slug>` not found", in place of the content view. A deep-linked drive that is still arriving shows the pending view first.
140
- - A missing document still redirects to its drive.
141
- - A project route's own `notFoundComponent` handles its loader's `notFound()`; without one, Connect's 404 page shows in its place.
142
-
143
- ### Adding a settings tab
144
-
145
- Settings is a page at `/settings`, with one child route per tab (`/settings/package-manager`, `/settings/about`, ...). Bare `/settings` redirects to the first tab. The tab list is built from the children of `/settings` that declare `staticData.settings`, so a project adds a tab with a file in `_app/settings/`:
146
-
147
- ```tsx
148
- // hosts/connect/routes/_app/settings/reports.tsx
149
- import { createFileRoute } from "@tanstack/react-router";
150
- import { FileText } from "lucide-react";
151
-
152
- export const Route = createFileRoute("/_app/settings/reports")({
153
- // label, order (Connect's tabs use 0-90), optional icon, destructive and enabled(context)
154
- staticData: { settings: { label: "Reports", order: 50, icon: FileText } },
155
- component: ReportsSettings,
156
- });
157
- ```
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.
158
88
 
159
- - The page title becomes `Settings · Reports · <app>`; the tab needs no `head`.
160
- - A tab whose `enabled(context)` returns false is not listed, and its URL redirects to the first tab.
161
- - `_app/settings.tsx` itself belongs to Connect; a project file for it fails the build.
162
- - Code opens settings with `store.navigation.open({ settings: "reports" })` (or `{ settings: true }` for the first tab), or links to it with `useLinkProps`. `showPHModal({ type: "settings" })` is deprecated and opens the page.
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).
163
90
 
164
- Embedding apps that do not build with Vite add code routes through `@powerhousedao/connect/router` instead: create them with `getParentRoute: () => connectRoutes().appRoute` (or `.rootRoute` for a full page) and pass them to `createConnectRouter({ routes })`, or call `addConnectRoutes`.
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).
165
92
 
166
93
  ## Troubleshooting
167
94