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

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 (109) hide show
  1. package/README.md +1 -1
  2. package/RUNTIME-CONFIG.md +6 -85
  3. package/dist/{ClearStorageModal-BwGVIuLX.js → ClearStorageModal-DQv3ZGOq.js} +4 -4
  4. package/dist/{ClearStorageModal-BwGVIuLX.js.map → ClearStorageModal-DQv3ZGOq.js.map} +1 -1
  5. package/dist/{CreateDocumentModal-B-cXzeOA.js → CreateDocumentModal-CiIW3pzx.js} +18 -9
  6. package/dist/CreateDocumentModal-CiIW3pzx.js.map +1 -0
  7. package/dist/{DebugSettingsModal-DfOnR4iY.js → DebugSettingsModal-DjFwGop2.js} +6 -6
  8. package/dist/{DebugSettingsModal-DfOnR4iY.js.map → DebugSettingsModal-DjFwGop2.js.map} +1 -1
  9. package/dist/{InspectorModal-BVqRNFfP.js → InspectorModal-C1ZVZpT5.js} +6 -6
  10. package/dist/{InspectorModal-BVqRNFfP.js.map → InspectorModal-C1ZVZpT5.js.map} +1 -1
  11. package/dist/{OpenFileDocumentsModal-BNHD0vg9.js → OpenFileDocumentsModal-B9c-CsKT.js} +4 -4
  12. package/dist/{OpenFileDocumentsModal-BNHD0vg9.js.map → OpenFileDocumentsModal-B9c-CsKT.js.map} +1 -1
  13. package/dist/app-loader-ClDJbH8j.js +4 -0
  14. package/dist/{app-loader-DtH6v5CE.js → app-loader-DxGySldw.js} +41 -32
  15. package/dist/{app-loader-DtH6v5CE.js.map → app-loader-DxGySldw.js.map} +1 -1
  16. package/dist/{app-skeleton-DFg65Rxa.js → app-skeleton-BHgmbYld.js} +3 -3
  17. package/dist/{app-skeleton-BFjvlTWd.js → app-skeleton-ClRUYLE_.js} +14 -5
  18. package/dist/app-skeleton-ClRUYLE_.js.map +1 -0
  19. package/dist/{boot-N7f3RrY_.js → boot-D2-yDYJi.js} +5 -5
  20. package/dist/{boot-N7f3RrY_.js.map → boot-D2-yDYJi.js.map} +1 -1
  21. package/dist/{build-info-TgBEqTq1.js → build-info-CZ8K52c5.js} +5 -5
  22. package/dist/{build-info-TgBEqTq1.js.map → build-info-CZ8K52c5.js.map} +1 -1
  23. package/dist/{components-B_wpF5Is.js → components-B36iVkNp.js} +8 -8
  24. package/dist/{components-B_wpF5Is.js.map → components-B36iVkNp.js.map} +1 -1
  25. package/dist/{connect.config-D1pGNmaF.js → connect.config-DL9nKtlW.js} +6 -5
  26. package/dist/connect.config-DL9nKtlW.js.map +1 -0
  27. package/dist/{connection-state-B6fleM37.js → connection-state-Bwm9Agwy.js} +4 -4
  28. package/dist/{connection-state-B6fleM37.js.map → connection-state-Bwm9Agwy.js.map} +1 -1
  29. package/dist/{cookie-banner-CAvd3PC3.js → cookie-banner-NclLYtB0.js} +4 -4
  30. package/dist/{cookie-banner-CAvd3PC3.js.map → cookie-banner-NclLYtB0.js.map} +1 -1
  31. package/dist/{drive-icon-BiVP8yJc.js → drive-icon-BIpd8edR.js} +14 -3
  32. package/dist/drive-icon-BIpd8edR.js.map +1 -0
  33. package/dist/generic.d.ts +20 -2
  34. package/dist/generic.d.ts.map +1 -1
  35. package/dist/generic.js +2 -2
  36. package/dist/{load-CkbGF6wB.js → load-C2wlvi5d.js} +9 -9
  37. package/dist/{load-CkbGF6wB.js.map → load-C2wlvi5d.js.map} +1 -1
  38. package/dist/{load-runtime-config-DXswYA71.js → load-runtime-config-BeZF5z7m.js} +4 -4
  39. package/dist/{load-runtime-config-DXswYA71.js.map → load-runtime-config-BeZF5z7m.js.map} +1 -1
  40. package/dist/main.js +2 -2
  41. package/dist/{package-manager-CPqbVSd8.js → package-manager-dfP4R5L3.js} +11 -10
  42. package/dist/{package-manager-CPqbVSd8.js.map → package-manager-dfP4R5L3.js.map} +1 -1
  43. package/dist/{pglite-seed-eGzXMld2.js → pglite-seed-QPbGbLB_.js} +4 -4
  44. package/dist/{pglite-seed-eGzXMld2.js.map → pglite-seed-QPbGbLB_.js.map} +1 -1
  45. package/dist/plugin-configs.d.ts +242 -0
  46. package/dist/plugin-configs.d.ts.map +1 -0
  47. package/dist/plugin-configs.js +26 -0
  48. package/dist/plugin-configs.js.map +1 -0
  49. package/dist/plugins-DV3oFEmL.js +263 -0
  50. package/dist/plugins-DV3oFEmL.js.map +1 -0
  51. package/dist/{preferences-store-CSqauT9V.js → preferences-store-DxYAnGCc.js} +4 -4
  52. package/dist/{preferences-store-CSqauT9V.js.map → preferences-store-DxYAnGCc.js.map} +1 -1
  53. package/dist/prerender.d.ts.map +1 -1
  54. package/dist/prerender.js +18 -7
  55. package/dist/prerender.js.map +1 -1
  56. package/dist/{reactor-DLCl-WHi.js → reactor-DT1kVwnf.js} +12 -7
  57. package/dist/{reactor-DLCl-WHi.js.map → reactor-DT1kVwnf.js.map} +1 -1
  58. package/dist/{registerServiceWorker-APlHkrmH.js → registerServiceWorker-X6fT91iL.js} +4 -4
  59. package/dist/{registerServiceWorker-APlHkrmH.js.map → registerServiceWorker-X6fT91iL.js.map} +1 -1
  60. package/dist/route-tree.js +1 -1
  61. package/dist/{route-views-CTARvT5N.js → route-views-2aB1ZZPP.js} +6 -6
  62. package/dist/route-views-2aB1ZZPP.js.map +1 -0
  63. package/dist/route-views-D_873yb_.js +4 -0
  64. package/dist/{route-views-BF0p-4Fi.js → route-views-DmmQ1DzX.js} +5 -5
  65. package/dist/{route-views-BF0p-4Fi.js.map → route-views-DmmQ1DzX.js.map} +1 -1
  66. package/dist/route-views.js +3 -3
  67. package/dist/router-CBzb5FUq.js +4 -0
  68. package/dist/{router-L9X9U-97.js → router-DXpaaTeR.js} +15 -7
  69. package/dist/router-DXpaaTeR.js.map +1 -0
  70. package/dist/{settings-B-apZN_f.js → settings-BwKo6EAU.js} +17 -10
  71. package/dist/{settings-B-apZN_f.js.map → settings-BwKo6EAU.js.map} +1 -1
  72. package/dist/{settings-tabs-CRgiuZcb.js → settings-tabs-BubPdsiT.js} +51 -19
  73. package/dist/settings-tabs-BubPdsiT.js.map +1 -0
  74. package/dist/shell-core.html +1 -1
  75. package/dist/shell-head.html +1 -1
  76. package/dist/shell.html +1 -1
  77. package/dist/start-connect.js +2 -2
  78. package/dist/style.css +109 -4
  79. package/dist/{ui-CwbE23ra.js → ui-BVOQ9tj_.js} +8 -8
  80. package/dist/{ui-CwbE23ra.js.map → ui-BVOQ9tj_.js.map} +1 -1
  81. package/dist/workflows-C3qEvx1R.js +63 -0
  82. package/dist/workflows-C3qEvx1R.js.map +1 -0
  83. package/docs/customizing/data-and-navigation.md +50 -0
  84. package/docs/customizing/drive-apps.md +42 -0
  85. package/docs/customizing/hosts-and-plugins.md +23 -0
  86. package/docs/customizing/layout.md +9 -2
  87. package/docs/customizing/modals.md +25 -4
  88. package/docs/customizing/overrides.md +59 -4
  89. package/docs/customizing/packages.md +2 -0
  90. package/docs/customizing/pages.md +10 -13
  91. package/docs/customizing/styles-and-branding.md +9 -2
  92. package/docs/customizing/types-and-troubleshooting.md +4 -2
  93. package/generic-routes.json +9 -0
  94. package/package.json +26 -19
  95. package/scripts/assert-plugin-configs.mjs +47 -0
  96. package/skills/customize-connect/SKILL.md +14 -11
  97. package/CUSTOMIZING.md +0 -80
  98. package/dist/CreateDocumentModal-B-cXzeOA.js.map +0 -1
  99. package/dist/app-loader-BjAXSJQ6.js +0 -4
  100. package/dist/app-skeleton-BFjvlTWd.js.map +0 -1
  101. package/dist/connect.config-D1pGNmaF.js.map +0 -1
  102. package/dist/drive-icon-BiVP8yJc.js.map +0 -1
  103. package/dist/plugins-CWbr0n_Q.js +0 -246
  104. package/dist/plugins-CWbr0n_Q.js.map +0 -1
  105. package/dist/route-views-CTARvT5N.js.map +0 -1
  106. package/dist/route-views-D8I-1PWU.js +0 -4
  107. package/dist/router-BguOMBUh.js +0 -4
  108. package/dist/router-L9X9U-97.js.map +0 -1
  109. package/dist/settings-tabs-CRgiuZcb.js.map +0 -1
@@ -16,10 +16,13 @@ import {
16
16
  SidebarItem,
17
17
  useSidebarMode,
18
18
  } from "@powerhousedao/connect/generic";
19
+ import { options } from "@powerhousedao/connect/routes/_app";
19
20
  import { isPlainClick } from "@powerhousedao/reactor-browser";
20
21
  import { createFileRoute, useRouter } from "@tanstack/react-router";
21
22
 
22
23
  export const Route = createFileRoute("/_app")({
24
+ // Empty today; spread so an option Connect adds later isn't dropped.
25
+ ...options,
23
26
  component: Layout,
24
27
  });
25
28
 
@@ -53,11 +56,14 @@ function Layout() {
53
56
  }
54
57
  ```
55
58
 
59
+ - The sidebar shows only icons. `title` is the item's tooltip and its accessible name, and `description` is shown in the tooltip under it and read as its description. An item without an `icon` shows the title's first letter.
60
+ - On a phone, `ConnectSidebar` is a bar under the page, with the items in a row: rendered by `AppLayout`, passed as `sidebar`, or rendered by a component of yours that is. Any other `sidebar` keeps the place its markup gives it.
61
+
56
62
  A plain `href` makes the browser load the whole app again. Use it for external links only. For a link inside Connect, navigate through the router, as the "Focus" item does, or render the router's `Link`. `isPlainClick` leaves modified clicks (new tab, new window) to the browser.
57
63
 
58
64
  ## Replace the layout
59
65
 
60
- `@powerhousedao/connect/layout` exports core's parts to build a different layout, and `@powerhousedao/connect/generic` the generic plugin's as well. A layout that imports only from `/layout` doesn't load the generic UI:
66
+ `@powerhousedao/connect/layout` exports core's parts to build a different layout, and `@powerhousedao/connect/generic` the generic plugin's as well. `/generic` re-exports everything in `/layout`, so either import works for a `/layout` part. A layout that imports only from `/layout` doesn't load the generic UI:
61
67
 
62
68
  | Export | From | What it is |
63
69
  | --- | --- | --- |
@@ -65,7 +71,7 @@ A plain `href` makes the browser load the whole app again. Use it for external l
65
71
  | `ConnectSidebar` | `/generic` | Connect's sidebar; `extraItems`, `collapsed`. |
66
72
  | `SidebarDriveItems` | `/generic` | The drive items and the add-drive item. |
67
73
  | `SidebarNavItems` | `/generic` | The `staticData.nav` items. |
68
- | `SidebarItem` | `/layout` | One sidebar item. |
74
+ | `SidebarItem` | `/layout` | One sidebar item: `title`, `icon` (an element, unlike `staticData.nav`'s component), `description`, `href` or `onClick`. |
69
75
  | `useNavRoutes()` | `/layout` | The `staticData.nav` routes, sorted: `{ label, icon, order, routeId, to }`. |
70
76
  | `useSidebarMode()` | `/layout` | The current route's `staticData.sidebar`. |
71
77
  | `ContentOutlet` | `/layout` | The matched route, in the container whose scroll Connect resets on new pages and restores on back and forward. |
@@ -143,6 +149,7 @@ export const Route = createFileRoute("/_app")({
143
149
 
144
150
  - Without a `pendingComponent` on `_app`, the loading screen shows core's spinner.
145
151
  - The render runs at build time, in Node, with no drives: components on the path to `/` must not touch `window` while rendering, and should show nothing for data that isn't there yet (e.g. `useDrives()` is `undefined`).
152
+ - Studio renders the screen too, at start and on route edits. If it fails, Studio shows the error over the page and in its log, since `ph connect build` fails on it.
146
153
  - On a deep link the screen is the same, with no tab marked current; the page appears once the app routes.
147
154
  - The screen's CSS is inlined: Tailwind builds the project's `style.css` for just the classes in the screen's markup, with its tokens and rules and without third-party CSS. The full stylesheet loads without blocking the first paint.
148
155
  - `staticData.nav` items are links the layout renders, so they appear on the loading screen; drives arrive later, so put them after the static items to avoid a shift.
@@ -19,12 +19,29 @@ Editors, drive apps and Connect open modals with `showPHModal(modal)` from `@pow
19
19
  - **Core** has a plain view for each of its modals, so every host can show what editors and drive apps open.
20
20
  - **With the generic plugin**, Connect shows its design-system views for all of them; without it, core's.
21
21
 
22
+ A plain `<a href={modalHref(modal)}>` reloads the app. `useModalLinkProps(modal)` gives a link that opens the modal in place on a plain click, and its URL to new tabs and copied links:
23
+
24
+ ```tsx
25
+ import { useModalLinkProps } from "@powerhousedao/reactor-browser";
26
+
27
+ const modal = { type: "createDocument", documentType: "powerhouse/todo" } as const;
28
+
29
+ function NewTodoListLink() {
30
+ return <a {...useModalLinkProps(modal)}>New todo list</a>;
31
+ }
32
+ ```
33
+
34
+ - The href follows the page's query params as they change.
35
+ - Confirmations (`deleteItem` and the like) aren't routed, so their link has no URL of its own; open them with `showPHModal(modal)` from a button.
36
+ - `createDocument` creates in the open drive, and its open folder, then opens the new document in its drive, wherever the modal was opened. Outside a drive it asks which drive, preselecting the only one, and offers to add a drive when there is none. Give it `driveId` to choose the drive yourself, e.g. `{ type: "createDocument", documentType: "powerhouse/todo", driveId }`.
37
+
22
38
  ## Replace a modal's view
23
39
 
24
40
  A route's `staticData.modals` replaces the host's view of a modal while the route matches; the deepest matched route wins. The view reads the modal with `usePHModal()`:
25
41
 
26
42
  ```tsx
27
43
  // hosts/connect/routes/_app.tsx
44
+ import { ModalDialog } from "@powerhousedao/connect/layout";
28
45
  import { closePHModal, usePHModal } from "@powerhousedao/reactor-browser";
29
46
 
30
47
  export const Route = createFileRoute("/_app")({
@@ -36,19 +53,23 @@ function CreateTodoList() {
36
53
  const modal = usePHModal();
37
54
  if (modal?.type !== "createDocument") return null;
38
55
  return (
39
- <dialog open>
40
- New {modal.documentType}
56
+ <ModalDialog labelledBy="new-todo-list" className="rounded-xl p-6">
57
+ <h2 id="new-todo-list">New {modal.documentType}</h2>
41
58
  <button onClick={closePHModal}>Cancel</button>
42
- </dialog>
59
+ </ModalDialog>
43
60
  );
44
61
  }
45
62
  ```
46
63
 
64
+ - `ModalDialog` opens the view as a modal, centred, with a backdrop; Escape and a click on the backdrop close it. A plain `<dialog open>` gets none of that.
65
+
47
66
  - On an override of one of Connect's routes, spread `options.staticData` first if it has any.
48
67
  - A view that throws closes quietly; the error is logged.
49
68
 
50
69
  ## Frame every modal
51
70
 
71
+ A frame applies only in a host whose composition leaves out the generic plugin: the generic plugin, active in a default Connect, draws every modal with the design system.
72
+
52
73
  A route's `staticData.modalFrame` lays out every core modal while the route matches, so one component restyles all of them. Each modal passes its title, content and buttons; `ModalDialog` keeps the dialog's behaviour (modal, Escape and the backdrop close it):
53
74
 
54
75
  ```tsx
@@ -73,6 +94,6 @@ function Frame({ title, titleId, actions, children }: ModalFrameProps) {
73
94
  ```
74
95
 
75
96
  - The deepest matched route's frame wins, as with `staticData.modals`. On `_app` it frames the modals opened inside the layout; on the root route, all of them.
76
- - It frames core's modals. The generic plugin's design-system modals, and views a route gives in `staticData.modals`, draw their own.
97
+ - It frames core's modals only. Views a route gives in `staticData.modals` draw their own.
77
98
  - The content and buttons keep core's markup; style them from the frame, e.g. with `[&_button]:…` classes.
78
99
 
@@ -37,10 +37,63 @@ function InventoryDrive() {
37
37
 
38
38
  - `useDriveRouteData()` returns the open `drive`, `folder` and `documentId` from the drive routes' loaders, live.
39
39
  - Connect's routes nested under an overridden one stay: the node route renders in an overridden drive route's `<Outlet />`, and the tabs in an overridden settings page's.
40
- - Drive apps and editors come from packages, not routes. Override a route only to change Connect around them.
40
+ - Drive apps and editors come from packages, not routes ([drive-apps.md](./drive-apps.md)). Override a route only to change Connect around them.
41
41
  - Without the generic plugin, each of Connect's files shows core's view instead (a header, an index of drives, a directory listing, a JSON view). An override shows the same view either way.
42
42
  - `_app.tsx` and `__root.tsx` are not overridden here: a project's `_app.tsx` replaces the layout ([layout.md](./layout.md)), and the root route is Connect's.
43
43
  - To hide a route, override it with a `beforeLoad` that throws `notFound()` or `redirect()`.
44
+ - `ph build` and Studio warn about an override that doesn't import its route's `options`: what Connect sets on the route is dropped.
45
+
46
+ ### Build on the home page
47
+
48
+ `Home` is made of parts that `/generic` exports, so a custom home keeps Connect's drive cards and adds its own:
49
+
50
+ ```tsx
51
+ // hosts/connect/routes/_app/index.tsx
52
+ import {
53
+ ConnectHomeScreen,
54
+ HomeAddDriveItem,
55
+ HomeDriveItem,
56
+ useVisibleDrives,
57
+ } from "@powerhousedao/connect/generic";
58
+ import { options } from "@powerhousedao/connect/routes/_app/index";
59
+ import { HomeScreenItem } from "@powerhousedao/design-system/connect";
60
+ import { createFileRoute, useNavigate } from "@tanstack/react-router";
61
+
62
+ export const Route = createFileRoute("/_app/")({
63
+ ...options,
64
+ component: InventoryHome,
65
+ });
66
+
67
+ // A card like the drives', for a page of the project's own.
68
+ function OpenOrdersCard() {
69
+ const navigate = useNavigate();
70
+ return (
71
+ <HomeScreenItem
72
+ title="Open orders"
73
+ description="Orders on the floor"
74
+ onClick={() => void navigate({ to: "/orders" })}
75
+ />
76
+ );
77
+ }
78
+
79
+ function InventoryHome() {
80
+ const drives = useVisibleDrives();
81
+ return (
82
+ <ConnectHomeScreen>
83
+ <OpenOrdersCard />
84
+ {drives?.map((drive) => (
85
+ <HomeDriveItem key={drive.header.id} drive={drive} />
86
+ ))}
87
+ <HomeAddDriveItem />
88
+ </ConnectHomeScreen>
89
+ );
90
+ }
91
+ ```
92
+
93
+ - `ConnectHomeScreen` is the grid on the configured `branding.homeBackground`.
94
+ - `useVisibleDrives()` is `useDrives()` without the drives dismissed from the sign-in gate this session.
95
+ - `HomeAddDriveItem` renders nothing where adding drives is turned off.
96
+ - `HomeScreenItem` (`@powerhousedao/design-system/connect`) is the card the drives use: `title`, `description`, an `icon` element, and `href` or `onClick`.
44
97
 
45
98
  ## Loading, not found and errors
46
99
 
@@ -71,7 +124,7 @@ export const Route = createFileRoute("/_app/d/$driveSlug")({
71
124
  // hosts/connect/routes/_app/d/$driveSlug.tsx
72
125
  import { isDriveNotFound } from "@powerhousedao/connect/router";
73
126
  import { options } from "@powerhousedao/connect/routes/_app/d/$driveSlug";
74
- import type { NotFoundRouteProps } from "@tanstack/react-router";
127
+ import { createFileRoute, type NotFoundRouteProps } from "@tanstack/react-router";
75
128
 
76
129
  export const Route = createFileRoute("/_app/d/$driveSlug")({
77
130
  ...options,
@@ -84,6 +137,8 @@ export const Route = createFileRoute("/_app/d/$driveSlug")({
84
137
  A project route throws `notFound()` the same way:
85
138
 
86
139
  ```tsx
140
+ import { createFileRoute, notFound } from "@tanstack/react-router";
141
+
87
142
  export const Route = createFileRoute("/_app/documents/$documentId")({
88
143
  loader: async ({ context, params }) => {
89
144
  // ...
@@ -96,14 +151,14 @@ export const Route = createFileRoute("/_app/documents/$documentId")({
96
151
 
97
152
  ### Errors
98
153
 
99
- A loader or render error shows the route's `errorComponent`, else Connect's error view (with the generic plugin) or core's. It gets `{ error, reset }`; `reset()` retries the route. Connect reports the error to Sentry when Sentry is configured.
154
+ A loader or render error shows the route's `errorComponent`, else Connect's error view (with the generic plugin) or core's. It gets `{ error, reset }`; `error` is `unknown`, since anything can be thrown, and `reset()` retries the route. Connect reports the error to Sentry when Sentry is configured.
100
155
 
101
156
  ```tsx
102
157
  export const Route = createFileRoute("/_app/reports")({
103
158
  loader: loadReports,
104
159
  errorComponent: ({ error, reset }) => (
105
160
  <div role="alert">
106
- <p>{error.message}</p>
161
+ <p>{error instanceof Error ? error.message : "Something went wrong"}</p>
107
162
  <button onClick={reset}>Try again</button>
108
163
  </div>
109
164
  ),
@@ -11,6 +11,8 @@ A package's `hosts/connect/routes/` also adds routes to every Connect that loads
11
11
  - Removing a package while one of its pages is open takes the app home first.
12
12
  - Bundled packages (`ph install --local`, `provider: "local"`) register in a production build through the page's import map, as on the dev server.
13
13
  - An offered route imports `@powerhousedao/connect-core` (`ContentOutlet`, `useDriveRouteData`, `ModalDialog`), `@tanstack/react-router` and `@powerhousedao/reactor-browser`, which Connect shares with packages. `@powerhousedao/connect` is not shared, so `ph build` fails, naming the file, if an offered route imports it, or reaches a module that does. The rest of the package gets a warning: its build would bundle a copy of the Connect modules it uses, apart from the app's state.
14
+ - An offered route also imports its own package's code, such as `document-models/*` and editor components, which the same build bundles. Another package's runtime import, e.g. `@powerhousedao/shared` (usually only a devDependency), is bundled as a copy; take the same helper from `@powerhousedao/reactor-browser` where it has one, e.g. `isFileNodeKind`.
15
+ - `@powerhousedao/connect/layout` re-exports `@powerhousedao/connect-core/router` and design-system parts. An offered route imports those directly: `useNavRoutes`, `useSidebarMode` and `ContentOutlet` from `@powerhousedao/connect-core/router`, `SidebarItem` from `@powerhousedao/design-system/connect`.
14
16
  - The project's own package is the exception: its host build already has its routes.
15
17
  - The package's stylesheet styles its routes, as it does its editors; see [A package's styles](./styles-and-branding.md#a-packages-styles).
16
18
 
@@ -4,13 +4,9 @@ A project adds pages to Connect with file routes in `hosts/connect/routes/`. A r
4
4
 
5
5
  ## Add a page
6
6
 
7
- 1. Add the router to the project, in the version Connect uses (the `@tanstack/react-router` entry in `@powerhousedao/connect`'s `package.json`):
7
+ Routes import `@tanstack/react-router`. A project from `ph init` has it as a `peerDependency`, and as a `devDependency` at the version Connect is built with; `ph migrate` adds it to an older project. Connect uses the project's copy, so keep that version rather than adding another.
8
8
 
9
- ```bash
10
- pnpm add @tanstack/react-router@1.170.41
11
- ```
12
-
13
- 2. Create a route file. A file in `_app/` renders inside Connect's layout; its route id starts with `/_app`, and the URL does not:
9
+ 1. Create a route file. A file in `_app/` renders inside Connect's layout; its route id starts with `/_app`, and the URL does not:
14
10
 
15
11
  ```tsx
16
12
  // hosts/connect/routes/_app/inventory.tsx
@@ -27,7 +23,7 @@ A project adds pages to Connect with file routes in `hosts/connect/routes/`. A r
27
23
  }
28
24
  ```
29
25
 
30
- 3. Run `ph connect studio` and open `/inventory`.
26
+ 2. Open `/inventory` in Studio: `ph vetra` if it's running, else `ph connect studio`. Run only one: each has its own reactor.
31
27
 
32
28
  A file outside `_app/` is a full page, without Connect's layout:
33
29
 
@@ -54,11 +50,12 @@ function Status() {
54
50
  Rules:
55
51
 
56
52
  - Connect reads routes only from `hosts/connect/routes/`.
57
- - Core routes are `/`, `/d/$driveSlug/{-$nodeSlug}`, `/settings` with its Appearance and Packages tabs, and the catch-all `$`. They live in `@powerhousedao/connect-core`. A file in `_app/` at a core route's path overrides it; see [Override a Connect route](./overrides.md#override-a-connect-route). Any other route at a core route's URL fails the build.
53
+ - Core routes are `/`, `/d/$driveSlug/{-$nodeSlug}`, `/settings` with its Appearance and Packages tabs, and the catch-all `$`. They live in `@powerhousedao/connect-core`. A file in `_app/` at a core route's path overrides it; see [Override a Connect route](./overrides.md#override-a-connect-route). Any other route at a URL Connect serves, e.g. a full page `settings.tsx` outside `_app/`, fails the build and names both files.
58
54
  - Files and folders starting with `-` are not routes. Use them for shared components.
59
55
  - Route groups, `(name)/`, only organize files.
60
56
  - Each route is code-split into its own chunk.
61
57
  - Inside a route, navigate with the router's `Link` and `useNavigate`. They are typed with the project's routes and Connect's.
58
+ - A route file's `createFileRoute("…")` id must match its path. While Studio runs, the router's watcher rewrites a mismatched id in the file itself, under your editor; without Studio, `tsc` reports it.
62
59
 
63
60
  ## Add a sidebar link
64
61
 
@@ -67,14 +64,14 @@ A route in `_app/` lists itself in the sidebar with `staticData.nav`:
67
64
  ```tsx
68
65
  // hosts/connect/routes/_app/inventory.tsx
69
66
  export const Route = createFileRoute("/_app/inventory")({
70
- staticData: { nav: { label: "Inventory", icon: BoxIcon, order: 10 } },
67
+ staticData: { nav: { label: "Inventory", order: 10 } },
71
68
  component: Inventory,
72
69
  });
73
70
  ```
74
71
 
75
72
  - Links come after the drives, sorted by `order`, then by `label`.
76
- - `icon` is optional: any component that takes `size` (and `className`), e.g. from `lucide-react`.
77
- - Routes with path params (`$id`) are not listed: the sidebar cannot fill in the param.
73
+ - `icon` is optional: any component that takes `size` (and `className`). Without one, the link shows the label's first letter.
74
+ - Routes with path params (`$id`) are not listed: the sidebar cannot fill in the param. `ph build` and Studio warn about a `nav` on one.
78
75
 
79
76
  ## Hide or collapse the sidebar on a page
80
77
 
@@ -113,9 +110,9 @@ export const Route = createFileRoute("/_app/settings/inventory")({
113
110
  });
114
111
  ```
115
112
 
116
- - `icon` and `destructive` are optional.
113
+ - `icon` (a component that takes `size`, as for a sidebar link) and `destructive` are optional.
117
114
  - The page title becomes `Settings · Inventory · <app>`. The tab needs no `head`.
118
- - The generic plugin adds its tabs (Package Manager, Default Editors, Danger Zone, About, AI Assistant) as code routes and hides core's (Appearance, Packages); without it, core's are listed. A project file at a tab's path, e.g. `_app/settings/about.tsx`, replaces that tab; it spreads the tab's options from `genericSettingsTabs` (`@powerhousedao/connect/generic`), e.g. `...genericSettingsTabs.about`, to keep its label, icon and order.
115
+ - The generic plugin adds its tabs (Package Manager, Default Editors, Danger Zone, About, AI Assistant) as code routes and hides core's (Appearance, Packages); without it, core's are listed. A project file at a tab's path, e.g. `_app/settings/about.tsx`, replaces that tab; it spreads the tab's options from `genericSettingsTabs` (`@powerhousedao/connect/generic`), e.g. `...genericSettingsTabs.about`, to keep its label, icon and order. Like an override of Connect's routes, it stays this project's: `ph build` doesn't offer it to other Connects, so it may import `@powerhousedao/connect`.
119
116
 
120
117
  ## Set the page title
121
118
 
@@ -25,7 +25,13 @@ A project's styles are in two files, which the page builds as one Tailwind build
25
25
  --color-red-700: #b42318;
26
26
  }
27
27
 
28
+ /* A semantic token: set its light value and its dark one. */
29
+ :root {
30
+ --primary: #0a5bc4;
31
+ }
32
+
28
33
  :root.dark {
34
+ --primary: #6aa8ff;
29
35
  --background: #16181c;
30
36
  }
31
37
  ```
@@ -36,6 +42,7 @@ A project's styles are in two files, which the page builds as one Tailwind build
36
42
  - Theme Connect in the host's file: override tokens in `@theme static`, and add plain CSS below it. Tailwind emits only the tokens the page's own classes use, so without `static` an override of a token only a package uses never reaches the page, and the package's class keeps Connect's default. A fully static theme would add about 11 KB (3 KB gzipped) to the page; `static` on the host's own block adds just its overrides. Plain rules outside a `@layer` win over all of Connect's CSS, which is layered; put a rule in `@layer components` to let utilities override it.
37
43
  - The host's file sits beside its routes folder: `hosts/connect/style.css` for `hosts/connect/routes/`, `hosts/lab/style.css` for a host whose `runner.routes` is `hosts/lab/routes`. `ph connect studio`, `build` and `preview`, `ph vetra` and `ph run <host>` add it, and the loading screen's inline CSS includes it. Studio applies edits to it without a reload.
38
44
  - The design system defines the `dark` variant (`.dark` on `<html>`), so a project's `dark:` classes follow Connect's theme toggle.
45
+ - The semantic tokens (`--background`, `--foreground`, `--primary`, `--muted`, `--border`, ... in the design system's `theme.css`) are the ones to override. Each has a light value on `:root` and a dark one on `.dark`, so set both: a `:root` override alone ties with `.dark`, comes later, and wins in the dark theme too.
39
46
  - `ph migrate` rewrites the imports at the top of an existing `style.css` to these and keeps the rest of the file. It drops the imports of local packages' builds that `ph install --local` used to add (other `node_modules` CSS stays) and the old template's empty `@theme` block, adds `properties` to an old layer order, creates `hosts/connect/style.css` when it is missing (a host with its own `runner.routes` creates its file by hand), and warns when `style.css` sets tokens or global rules (`:root`, `html`, `body`, `.dark`). It doesn't move them: only the project knows which are the package's and which are this Connect's theme.
40
47
 
41
48
  ## A package's styles
@@ -52,7 +59,7 @@ A project's styles are in two files, which the page builds as one Tailwind build
52
59
 
53
60
  ## Name and icon per host
54
61
 
55
- `connect.branding.appName` and `connect.branding.favicon` in `powerhouse.config.json` name the app and set its tab icon for every host. A host overrides either in its `config`:
62
+ `connect.branding.appName` and `connect.branding.favicon` in `powerhouse.config.json` name the app and set its tab icon for every host. The app name also names the installed app (the PWA manifest), unless `connect.pwa.manifest` sets `name` or `short_name`; its icons, and the tab's when there's no `favicon`, come from `connect.branding.icon` (see [RUNTIME-CONFIG.md](../../RUNTIME-CONFIG.md)). A running `ph vetra` or `ph connect studio` reads `connect.branding` at startup: restart it after changing it. A host overrides either in its `config`:
56
63
 
57
64
  ```js
58
65
  // hosts/lab/host.js
@@ -64,6 +71,6 @@ export default {
64
71
  ```
65
72
 
66
73
  - A host's `config` merges over the project's `connect` block field by field, so a host inherits what it doesn't set.
67
- - `branding.favicon` is a file (`.ico`, `.svg` or `.png`) relative to the project. `ph run lab dev` serves it and `ph run lab build` builds it as `icon.ico`; the built `powerhouse.config.json` leaves the path out. `ph connect build --favicon` wins over it.
74
+ - `branding.favicon` is a file (`.ico`, `.svg` or `.png`) relative to the project. `ph run lab dev` serves it and `ph run lab build` builds it with its type, as `icon.ico`, `icon.svg` or `icon.png`, and links it from `index.html`; the built `powerhouse.config.json` leaves the path out. `ph connect build --favicon` wins over it.
68
75
  - `ph run lab build` bakes the host's `config` into the build, over `powerhouse.config.json`: the `<title>` and the loading screen take its `branding.appName`, and the build uses its `app.basePath` and `pwa`.
69
76
 
@@ -8,7 +8,7 @@ The build generates `.ph/connect-routes.gen.ts`: the route tree of Connect's rou
8
8
  - The project's `tsconfig.json` includes `.ph/connect-routes.gen.ts` and maps both `"@powerhousedao/connect-core/route-tree"` and `"@powerhousedao/connect/route-tree"` to `["./.ph/connect-routes.gen.ts"]` in `paths`. New projects are scaffolded with them. In an older project, add them by hand, and drop `.ph` from `exclude`. Core's router types name the tree by `@powerhousedao/connect-core/route-tree`; without that path they use core's own routes.
9
9
  - Until the first build, both specifiers resolve to core's own tree. Project routes show type errors (unknown route ids) until `ph connect build` or `ph connect studio` has run.
10
10
  - `ph connect build` type-checks the routes and fails on errors. `--ignore-type-errors` skips the check.
11
- - `@tanstack/react-router` must be the version Connect uses. The routes and Connect share one router, and its types come from the project's copy.
11
+ - `@tanstack/react-router` is the project's own copy, which Connect uses too: keep the version `ph init` or `ph migrate` set. The routes and Connect share one router, and its types come from that copy.
12
12
 
13
13
  ## Troubleshooting
14
14
 
@@ -16,6 +16,7 @@ The build generates `.ph/connect-routes.gen.ts`: the route tree of Connect's rou
16
16
  | --- | --- |
17
17
  | `Connect could not mount the routes in hosts/connect/routes/` | A route outside `_app/` collides with one of Connect's, or two project files have one path. The message names the files. |
18
18
  | A new routes folder is ignored by a running `ph connect studio` | Connect checks for the folder at startup. Restart it. |
19
+ | `tsc` reports `TS2883: The inferred type of 'Route' cannot be named without a reference to 'ConnectRouterContext'` | The route tree hasn't been generated yet. Run `ph build` (or start Studio) once; the error goes with the unknown route ids. |
19
20
  | `createFileRoute("/_app/x")` is a type error | The tree is not generated yet, or the tsconfig lacks the `route-tree` path. See [Types](#types). |
20
21
  | A sidebar link reloads the whole app | It is a plain `href`. Navigate through the router; see [Replace the sidebar](./layout.md#replace-the-sidebar). |
21
22
  | A `staticData.nav` route is missing from the sidebar | Its path has a param, or it is not in `_app/`, or a replaced layout does not render `SidebarNavItems`/`useNavRoutes`. |
@@ -27,6 +28,7 @@ The build generates `.ph/connect-routes.gen.ts`: the route tree of Connect's rou
27
28
  | A host's token override doesn't reach a package's classes | The page emits only the tokens its own classes use. Override it in `@theme static` in the host's stylesheet; see [Styles](./styles-and-branding.md#styles). |
28
29
  | Installing a package re-themes Connect | The package's `style.css` sets Connect's tokens or global rules, which ship in its stylesheet. Move them to its `hosts/connect/style.css`; `ph migrate` warns about them. |
29
30
  | `ph build` fails: `./theme.css` is not exported from `@powerhousedao/connect` | The project's `@powerhousedao/connect` is older than `ph-cli`. Update it to the same version. |
31
+ | You want to see the route tree, matches and loader state | Studio shows TanStack's router devtools when the page has `?devtools=1`, or after `localStorage.setItem("ph:router-devtools", "1")`. They are off by default and never in a build. |
30
32
 
31
33
  ## Upgrading
32
34
 
@@ -57,7 +59,7 @@ In 6.2.3 dev prereleases only, `RouteSelection` and scoped PH stores (`createSco
57
59
  The generic plugin's UI moved behind the plugin, which a project's routes follow by hand:
58
60
 
59
61
  - `AppLayout`, `ConnectSidebar`, `SidebarDriveItems`, `SidebarNavItems` and `OpenDocument` import from `@powerhousedao/connect/generic`, not `/layout`.
60
- - `@powerhousedao/connect/route-views` exports only `ConnectRoot`; `Home`, `DriveLayout`, `NodeView`, `DrivePending` and `SettingsPage` import from `/generic`.
62
+ - `@powerhousedao/connect/route-views` exports only `ConnectRoot`; `Home` (and its parts), `DriveLayout`, `NodeView`, `DrivePending` and `SettingsPage` import from `/generic`.
61
63
  - `generic()`, `genericActive`, `IfPlugin` and `useIsPluginActive` are gone; a plugin's `ui()` provides its views.
62
64
  - Connect's About, AI Assistant, Danger Zone, Default Editors and Package Manager tabs are the generic plugin's code routes, so `@powerhousedao/connect/routes/_app/settings/<tab>` no longer exists for them. An override imports the tab's options as `genericSettingsTabs["<tab>"]` from `@powerhousedao/connect/generic` instead; links to these tabs are untyped, so use `useLinkProps({ settings: "<tab>" })`.
63
65
 
@@ -0,0 +1,9 @@
1
+ {
2
+ "appRoutes": [
3
+ "settings/ai-assistant",
4
+ "settings/package-manager",
5
+ "settings/default-editors",
6
+ "settings/danger-zone",
7
+ "settings/about"
8
+ ]
9
+ }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@powerhousedao/connect",
3
3
  "productName": "Powerhouse-Connect",
4
- "version": "6.2.3-dev.70",
4
+ "version": "6.2.3-dev.72",
5
5
  "description": "Powerhouse Connect",
6
6
  "main": "dist/index.html",
7
7
  "type": "module",
@@ -12,12 +12,12 @@
12
12
  "dist",
13
13
  "skills",
14
14
  "docs",
15
- "CUSTOMIZING.md",
16
15
  "RUNTIME-CONFIG.md",
17
16
  "src/routes",
18
17
  "src/router",
19
18
  "src/route-tree.ts",
20
19
  "src/routeTree.gen.ts",
20
+ "generic-routes.json",
21
21
  "style.css",
22
22
  "tailwind.css",
23
23
  "theme.css",
@@ -71,6 +71,12 @@
71
71
  "types": "./dist/route-views.d.ts",
72
72
  "import": "./dist/route-views.js"
73
73
  },
74
+ "./plugin-configs": {
75
+ "source": "./src/plugin-configs/index.ts",
76
+ "types": "./dist/plugin-configs.d.ts",
77
+ "import": "./dist/plugin-configs.js",
78
+ "default": "./dist/plugin-configs.js"
79
+ },
74
80
  "./routes/*": "./src/routes/*.tsx",
75
81
  "./assets/*": "./assets/*",
76
82
  "./style.css": "./dist/style.css",
@@ -104,28 +110,27 @@
104
110
  "@openfeature/core": "1.9.1",
105
111
  "@openfeature/web-sdk": "1.6.2",
106
112
  "@openpanel/web": "^1.4.1",
107
- "@powerhousedao/config": "6.2.3-dev.70",
108
- "@powerhousedao/connect-core": "6.2.3-dev.70",
109
- "@powerhousedao/design-system": "6.2.3-dev.70",
113
+ "@powerhousedao/config": "6.2.3-dev.72",
114
+ "@powerhousedao/connect-core": "6.2.3-dev.72",
115
+ "@powerhousedao/design-system": "6.2.3-dev.72",
110
116
  "@powerhousedao/document-engineering": "1.40.5",
111
- "@powerhousedao/host-core": "6.2.3-dev.70",
112
- "@powerhousedao/powerhouse-vetra-packages": "6.2.3-dev.70",
113
- "@powerhousedao/reactor": "6.2.3-dev.70",
114
- "@powerhousedao/reactor-attachments": "6.2.3-dev.70",
115
- "@powerhousedao/reactor-browser": "6.2.3-dev.70",
116
- "@powerhousedao/reactor-mcp": "6.2.3-dev.70",
117
- "@powerhousedao/reactor-router": "6.2.3-dev.70",
118
- "@powerhousedao/shared": "6.2.3-dev.70",
119
- "@powerhousedao/vetra": "6.2.3-dev.70",
120
- "@powerhousedao/workflow": "6.2.3-dev.70",
117
+ "@powerhousedao/host-core": "6.2.3-dev.72",
118
+ "@powerhousedao/powerhouse-vetra-packages": "6.2.3-dev.72",
119
+ "@powerhousedao/reactor": "6.2.3-dev.72",
120
+ "@powerhousedao/reactor-attachments": "6.2.3-dev.72",
121
+ "@powerhousedao/reactor-browser": "6.2.3-dev.72",
122
+ "@powerhousedao/reactor-mcp": "6.2.3-dev.72",
123
+ "@powerhousedao/reactor-router": "6.2.3-dev.72",
124
+ "@powerhousedao/shared": "6.2.3-dev.72",
125
+ "@powerhousedao/vetra": "6.2.3-dev.72",
126
+ "@powerhousedao/workflow": "6.2.3-dev.72",
121
127
  "@privy-io/react-auth": "3.35.0",
122
128
  "@rainbow-me/rainbowkit": "^2.2.11",
123
- "@renown/sdk": "6.2.3-dev.70",
129
+ "@renown/sdk": "6.2.3-dev.72",
124
130
  "@sentry/react": "^10.17.0",
125
131
  "@tailwindcss/node": "4.2.2",
126
132
  "@tanstack/react-query": "^5.90.2",
127
- "@tanstack/react-router": "^1.170.41",
128
- "document-model": "6.2.3-dev.70",
133
+ "document-model": "6.2.3-dev.72",
129
134
  "i18next": "^25.5.3",
130
135
  "kysely": "0.28.16",
131
136
  "kysely-pglite-dialect": "1.2.0",
@@ -143,6 +148,7 @@
143
148
  "devDependencies": {
144
149
  "@tailwindcss/cli": "4.2.2",
145
150
  "@tailwindcss/vite": "4.2.2",
151
+ "@tanstack/react-router": "^1.170.41",
146
152
  "@tanstack/react-router-devtools": "1.167.2",
147
153
  "@tanstack/router-core": "1.171.34",
148
154
  "@tanstack/router-plugin": "1.168.42",
@@ -165,6 +171,7 @@
165
171
  "vite-tsconfig-paths": "6.1.1"
166
172
  },
167
173
  "peerDependencies": {
174
+ "@tanstack/react-router": "^1.170.41",
168
175
  "react": ">=19.0.0",
169
176
  "react-dom": ">=19.0.0"
170
177
  },
@@ -174,7 +181,7 @@
174
181
  "test": "vitest --run",
175
182
  "dev": "vite dev",
176
183
  "build": "pnpm run build:bundle && pnpm run build:css && pnpm run build:shell",
177
- "build:bundle": "tsdown",
184
+ "build:bundle": "tsdown && node scripts/assert-plugin-configs.mjs",
178
185
  "build:css": "pnpm exec tailwindcss -i style.css -o dist/style.css",
179
186
  "build:shell": "vite build --config vite.prerender.config.ts --logLevel warn && node scripts/prerender-shell.ts",
180
187
  "build:debug": "cross-env PH_DEBUG_BUILD=true vite build",
@@ -0,0 +1,47 @@
1
+ // Fails the build when dist/plugin-configs.js (or any chunk it imports)
2
+ // imports anything beyond its zod-only allowlist: the entry must load in
3
+ // Node (`ph run` validates plugin entry configs with it) and in a browser,
4
+ // so it may not reach React, the DOM app, or a Node built-in.
5
+ import { existsSync, readFileSync } from "node:fs";
6
+ import path from "node:path";
7
+ import { fileURLToPath } from "node:url";
8
+
9
+ const dist = path.join(
10
+ path.dirname(fileURLToPath(import.meta.url)),
11
+ "..",
12
+ "dist",
13
+ );
14
+ const ENTRY = "plugin-configs.js";
15
+ const ALLOWED = new Set([
16
+ "zod",
17
+ "@powerhousedao/shared/connect/connect-config-schema",
18
+ "@powerhousedao/shared/host-tokens",
19
+ ]);
20
+ const IMPORT = /(?:\bfrom\s*|\bimport\s*\(?\s*)["']([^"']+)["']/g;
21
+
22
+ const failures = [];
23
+ const seen = new Set();
24
+ const queue = [ENTRY];
25
+ while (queue.length > 0) {
26
+ const file = queue.shift();
27
+ if (seen.has(file)) continue;
28
+ seen.add(file);
29
+ const full = path.join(dist, file);
30
+ if (!existsSync(full)) {
31
+ failures.push(`${file} is missing from dist/`);
32
+ continue;
33
+ }
34
+ for (const [, specifier] of readFileSync(full, "utf8").matchAll(IMPORT)) {
35
+ if (specifier.startsWith(".")) {
36
+ queue.push(path.posix.join(path.posix.dirname(file), specifier));
37
+ } else if (!ALLOWED.has(specifier)) {
38
+ failures.push(`${file} imports "${specifier}"`);
39
+ }
40
+ }
41
+ }
42
+
43
+ if (failures.length > 0) {
44
+ console.error(`${ENTRY} must stay zod-only:\n ${failures.join("\n ")}`);
45
+ process.exit(1);
46
+ }
47
+ console.log(`${ENTRY} is zod-only (${seen.size} file(s))`);
@@ -13,8 +13,9 @@ Connect is the Powerhouse web app that shows drives, documents and their editors
13
13
  | Pages, sidebar links, settings tabs, page titles | File routes in `hosts/connect/routes/` | [pages.md](../../docs/customizing/pages.md) |
14
14
  | Sidebar, layout, loading screen | `hosts/connect/routes/_app.tsx` | [layout.md](../../docs/customizing/layout.md) |
15
15
  | Home, drive view, open document, settings page, 404 | A route file at Connect's route path | [overrides.md](../../docs/customizing/overrides.md) |
16
- | Loading data, search params, links from editors | Route `loader`, `validateSearch`; `@powerhousedao/reactor-browser` | [data-and-navigation.md](../../docs/customizing/data-and-navigation.md) |
16
+ | Loading data, documents of one type across drives and links to them, search params, links from editors | Route `loader`, `validateSearch`; `useDocumentsOfType` and the other `@powerhousedao/reactor-browser` hooks | [data-and-navigation.md](../../docs/customizing/data-and-navigation.md) |
17
17
  | Modals | `staticData.modals`, `staticData.modalFrame` | [modals.md](../../docs/customizing/modals.md) |
18
+ | A drive's own view, and which drive uses it | A package's drive app; the drive's `preferredEditor` | [drive-apps.md](../../docs/customizing/drive-apps.md) |
18
19
  | Colours, fonts, CSS; app name and favicon per host | `style.css`; `connect.branding` | [styles-and-branding.md](../../docs/customizing/styles-and-branding.md) |
19
20
  | Several Connects with different routes, config or plugins | `hosts/<name>/host.js` | [hosts-and-plugins.md](../../docs/customizing/hosts-and-plugins.md) |
20
21
  | Routes that ship with a package to other Connects | The package's `hosts/connect/routes/` | [packages.md](../../docs/customizing/packages.md) |
@@ -26,10 +27,11 @@ These paths are relative to this file, inside `node_modules/@powerhousedao/conne
26
27
 
27
28
  - Connect routes with [TanStack Router](https://tanstack.com/router) file routes. The project's `hosts/connect/routes/` folder joins Connect's own routes in one router. `ph vetra`, `ph connect studio`, `ph connect build` and `ph build` all mount it.
28
29
  - A file in `_app/` renders inside Connect's layout, with the sidebar. Its route id starts with `/_app` but its URL does not: `_app/inventory.tsx` is `createFileRoute("/_app/inventory")` at `/inventory`. Any other file is a full page.
30
+ - A route's `loader` reads the app's PH store from the router context (`context.store`: drives, `reactorClient`, `documentCache`); components read live data with the `@powerhousedao/reactor-browser` hooks.
29
31
  - A route describes itself through `staticData`: `nav` lists it in the sidebar, `settings` makes it a settings tab, `sidebar` hides or collapses the sidebar, `modals` and `modalFrame` restyle modals.
30
- - Connect's routes come from `@powerhousedao/connect-core`. Each route file exports `options`, everything but the component. A project file at the same path spreads `options` and sets its own `component`.
32
+ - Connect's routes come from `@powerhousedao/connect-core`. Each route file exports `options`, everything but the component. A project file at the same path spreads `options` and sets its own `component`; `ph build` and Studio warn when it doesn't.
31
33
  - The generic plugin (`@powerhousedao/connect/plugins/generic`) draws Connect's sidebar, home, drive views and settings tabs. Without it, core's plain views show. A project's route files win over both.
32
- - `@powerhousedao/connect/layout` exports core's layout parts. `@powerhousedao/connect/generic` adds the generic plugin's parts (`AppLayout`, `ConnectSidebar`, `OpenDocument`, `genericSettingsTabs`).
34
+ - `@powerhousedao/connect/layout` exports core's layout parts. `@powerhousedao/connect/generic` adds the generic plugin's parts (`AppLayout`, `ConnectSidebar`, `OpenDocument`, `genericSettingsTabs`, and the home's `ConnectHomeScreen`, `HomeDriveItem`, `HomeAddDriveItem` and `useVisibleDrives`).
33
35
 
34
36
  ## A first page
35
37
 
@@ -37,10 +39,9 @@ These paths are relative to this file, inside `node_modules/@powerhousedao/conne
37
39
  // hosts/connect/routes/_app/inventory.tsx
38
40
  import { useDrives } from "@powerhousedao/reactor-browser";
39
41
  import { createFileRoute } from "@tanstack/react-router";
40
- import { Box } from "lucide-react";
41
42
 
42
43
  export const Route = createFileRoute("/_app/inventory")({
43
- staticData: { nav: { label: "Inventory", icon: Box, order: 10 } },
44
+ staticData: { nav: { label: "Inventory", order: 10 } },
44
45
  component: Inventory,
45
46
  });
46
47
 
@@ -52,23 +53,25 @@ function Inventory() {
52
53
 
53
54
  ## Rules that break builds
54
55
 
55
- - **Router version.** Add `@tanstack/react-router` to the project at exactly the version in `node_modules/@powerhousedao/connect/package.json`. The project's routes and Connect share one router.
56
+ - **One router.** `ph init` adds `@tanstack/react-router` as a peer and dev dependency at the version Connect is built with, and `ph migrate` adds it to older projects. Connect uses the project's copy, so don't add another version.
56
57
  - **Route ids match the file.** `createFileRoute("...")` takes the file's id, `/_app/...` for files in `_app/`. A route outside `_app/` at the URL of one of Connect's fails the build.
57
58
  - **Spread `options` when overriding** (`import { options } from "@powerhousedao/connect/routes/_app/..."`). Without them the route loses its loader, search params and title. The generic settings tabs have no route files: spread `genericSettingsTabs["<tab>"]` from `@powerhousedao/connect/generic` instead.
58
- - **Navigate through the router.** Use `Link`, `useNavigate` or `useLinkProps`. A plain `href` reloads the whole app, so keep it for external links.
59
+ - **Navigate through the router.** Use `Link`, `useNavigate` or `useLinkProps`. A plain `href` reloads the whole app, `modalHref()` links included, so keep it for external links; link to a modal with `useModalLinkProps(modal)`.
59
60
  - **One Tailwind build.** `style.css` imports `@powerhousedao/connect/tailwind.css`, never `@powerhousedao/connect/style.css` or a package's compiled CSS.
60
61
  - **The loading screen renders in Node.** `ph connect build` renders the layout and `_app`'s `pendingComponent` at build time, with no drives. Code on that path must not touch `window` while rendering, and must handle `useDrives()` being `undefined`.
61
- - **Package routes can't import `@powerhousedao/connect`.** Routes a package offers to other Connects import from `@powerhousedao/connect-core`, `@tanstack/react-router` and `@powerhousedao/reactor-browser` only.
62
+ - **Package routes can't import `@powerhousedao/connect`.** Routes a package offers to other Connects import from `@powerhousedao/connect-core`, `@tanstack/react-router`, `@powerhousedao/reactor-browser`, the design system and the package's own code. Overrides of Connect's routes and of the generic settings tabs stay the project's, so they may.
63
+ - **`ph run` needs a flag.** `FEATURE_UNIFORM_RUNNERS_ENABLED=1 ph run <host> dev|build|serve`; see hosts-and-plugins.md for its output folder and ports.
62
64
  - **Don't edit generated files.** `.ph/connect-routes.gen.ts` is regenerated from the routes folder.
63
65
 
64
66
  ## Check your work
65
67
 
66
- 1. Run Vetra (`ph vetra`) or `ph connect studio`, and open the route's URL. Restart it after creating the routes folder for the first time, because the folder is detected at startup.
68
+ `ph` is the global Powerhouse CLI (`ph-cmd`). A project without it runs the same commands with `pnpm exec ph-cli`, e.g. `pnpm exec ph-cli build`.
69
+
70
+ 1. Run Vetra (`ph vetra`) or `ph connect studio`, and open the route's URL. Restart it after creating the routes folder for the first time, because the folder is detected at startup. Studio shows a loading screen that fails to render over the page and in its log.
67
71
  2. Run `ph build`. It generates `.ph/connect-routes.gen.ts` and type-checks the routes. Unknown route ids in `createFileRoute`, `Link` or `useNavigate` mean the tree is stale or the tsconfig lacks the `route-tree` paths; see [types-and-troubleshooting.md](../../docs/customizing/types-and-troubleshooting.md).
68
72
  3. When the layout or `_app`'s `pendingComponent` changed, run `ph connect build`. It prerenders the loading screen and fails on code that touches `window` while rendering.
69
73
 
70
74
  ## Reading Connect's source
71
75
 
72
76
  - `node_modules/@powerhousedao/connect/src/routes/`: Connect's route files, the paths a project overrides.
73
- - `node_modules/@powerhousedao/connect-core/src/router/`: `staticData` types, the router context, search params and titles.
74
- - `node_modules/@powerhousedao/connect-core/src/routes/`: each core route's `options` and core's views.
77
+ - In `@powerhousedao/connect-core`'s folder, `src/router/` (`staticData` types, the router context, search params and titles) and `src/routes/` (each core route's `options` and core's views). pnpm doesn't link it into the project's `node_modules`; find it with `ls -d node_modules/.pnpm/@powerhousedao+connect-core@*/node_modules/@powerhousedao/connect-core`.