@powerhousedao/connect 6.2.3-dev.9 → 6.2.3-dev.90
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.
- package/README.md +29 -1
- package/dist/{AddDriveModal-xAw48kdl.js → AddDriveModal-zMepHdWt.js} +44 -18
- package/dist/AddDriveModal-zMepHdWt.js.map +1 -0
- package/dist/{ClearStorageModal-C1BXHTq3.js → ClearStorageModal-CDXvQxfJ.js} +11 -13
- package/dist/ClearStorageModal-CDXvQxfJ.js.map +1 -0
- package/dist/{ConfirmDocumentUpgradeModal-FUOhZsk7.js → ConfirmDocumentUpgradeModal-CoixS60F.js} +9 -8
- package/dist/ConfirmDocumentUpgradeModal-CoixS60F.js.map +1 -0
- package/dist/{CookiesPolicyModal-BpyPPyxS.js → CookiesPolicyModal-BpFjYc7T.js} +5 -5
- package/dist/{CookiesPolicyModal-BpyPPyxS.js.map → CookiesPolicyModal-BpFjYc7T.js.map} +1 -1
- package/dist/CreateDocumentModal-CiIW3pzx.js +45 -0
- package/dist/CreateDocumentModal-CiIW3pzx.js.map +1 -0
- package/dist/{DebugSettingsModal-ClqHzcxM.js → DebugSettingsModal-B02UGneJ.js} +11 -11
- package/dist/DebugSettingsModal-B02UGneJ.js.map +1 -0
- package/dist/{DeleteDriveModal-Dug84t1j.js → DeleteDriveModal-1pAIayG_.js} +7 -7
- package/dist/DeleteDriveModal-1pAIayG_.js.map +1 -0
- package/dist/{DeleteItemModal-mMzy3V8o.js → DeleteItemModal-BUpqmFxS.js} +8 -8
- package/dist/DeleteItemModal-BUpqmFxS.js.map +1 -0
- package/dist/{DisclaimerModal-DvpD5dPM.js → DisclaimerModal-TIJXRYLF.js} +7 -7
- package/dist/DisclaimerModal-TIJXRYLF.js.map +1 -0
- package/dist/{DocumentVersionUnsupportedModal-C3Q0V75l.js → DocumentVersionUnsupportedModal-DH9Zzsyw.js} +6 -6
- package/dist/DocumentVersionUnsupportedModal-DH9Zzsyw.js.map +1 -0
- package/dist/{DownloadDocumentWithErrorsModal-IKl0ljQb.js → DownloadDocumentWithErrorsModal-Beh-xw8B.js} +8 -7
- package/dist/DownloadDocumentWithErrorsModal-Beh-xw8B.js.map +1 -0
- package/dist/{DriveAuthRequiredModal-DVK7ZQzO.js → DriveAuthRequiredModal-XTcoJKvj.js} +7 -7
- package/dist/DriveAuthRequiredModal-XTcoJKvj.js.map +1 -0
- package/dist/DriveSettingsModal-CGZQhzBa.js +127 -0
- package/dist/DriveSettingsModal-CGZQhzBa.js.map +1 -0
- package/dist/FloatingTanStackRouterDevtools-CqogiFob-dxj8lrTP.js +2565 -0
- package/dist/FloatingTanStackRouterDevtools-CqogiFob-dxj8lrTP.js.map +1 -0
- package/dist/{InspectorModal-7FQBTEzt.js → InspectorModal-BECRjBej.js} +71 -31
- package/dist/InspectorModal-BECRjBej.js.map +1 -0
- package/dist/{LoginModal-CybbOm3N.js → LoginModal-O06ZvWFI.js} +8 -8
- package/dist/LoginModal-O06ZvWFI.js.map +1 -0
- package/dist/{OpenFileDocumentsModal-DGaYJpXW.js → OpenFileDocumentsModal-DJsC1oR1.js} +22 -16
- package/dist/OpenFileDocumentsModal-DJsC1oR1.js.map +1 -0
- package/dist/{UpgradeDriveModal-_8t9slxQ.js → UpgradeDriveModal-CCWKp5yn.js} +7 -7
- package/dist/UpgradeDriveModal-CCWKp5yn.js.map +1 -0
- package/dist/ai-tools-CSRAzPuU.js +41 -0
- package/dist/ai-tools-CSRAzPuU.js.map +1 -0
- package/dist/ai-tools-FwcvsTEc.js +4 -0
- package/dist/app-loader-B43UTqh-.js +4 -0
- package/dist/app-loader-DSYNwqKv.js +1254 -0
- package/dist/app-loader-DSYNwqKv.js.map +1 -0
- package/dist/app-skeleton-CMUP2zaz.js +132 -0
- package/dist/app-skeleton-CMUP2zaz.js.map +1 -0
- package/dist/app-skeleton-CdD1m8G3.js +4 -0
- package/dist/boot-JeVIsfm1.js +233 -0
- package/dist/boot-JeVIsfm1.js.map +1 -0
- package/dist/buffer-DNTcuap_.js +66 -0
- package/dist/buffer-DNTcuap_.js.map +1 -0
- package/dist/{build-info-D9_h0032.js → build-info-D0xL66Ow.js} +10 -6
- package/dist/build-info-D0xL66Ow.js.map +1 -0
- package/dist/components-DodkBJEK.js +121 -0
- package/dist/components-DodkBJEK.js.map +1 -0
- package/dist/{connect.config-DaHDEUrw.js → connect.config-DL9nKtlW.js} +28 -15
- package/dist/connect.config-DL9nKtlW.js.map +1 -0
- package/dist/{connection-state-3w4liC1X.js → connection-state-B6YMctkg.js} +20 -9
- package/dist/connection-state-B6YMctkg.js.map +1 -0
- package/dist/context-De2EB1AA-Ni0d829Q.js +1759 -0
- package/dist/context-De2EB1AA-Ni0d829Q.js.map +1 -0
- package/dist/{cookie-banner-BH6bIq24.js → cookie-banner-NclLYtB0.js} +7 -7
- package/dist/{cookie-banner-BH6bIq24.js.map → cookie-banner-NclLYtB0.js.map} +1 -1
- package/dist/document-editor-container-BuUPe031.js +4 -0
- package/dist/document-editor-container-C0lE2N2j.js +310 -0
- package/dist/document-editor-container-C0lE2N2j.js.map +1 -0
- package/dist/drive-icon-BIpd8edR.js +49 -0
- package/dist/drive-icon-BIpd8edR.js.map +1 -0
- package/dist/drive-placements-DjeVpTTm.js +38 -0
- package/dist/drive-placements-DjeVpTTm.js.map +1 -0
- package/dist/error-boundary-BsUBww61.js +155 -0
- package/dist/error-boundary-BsUBww61.js.map +1 -0
- package/dist/esm-BDACZntJ.js +148 -0
- package/dist/esm-BDACZntJ.js.map +1 -0
- package/dist/generic.d.ts +140 -0
- package/dist/generic.d.ts.map +1 -0
- package/dist/generic.js +31 -0
- package/dist/generic.js.map +1 -0
- package/dist/{i18n-CWO0vYVd.js → i18n-D9WYPgk9.js} +4 -4
- package/dist/{i18n-CWO0vYVd.js.map → i18n-D9WYPgk9.js.map} +1 -1
- package/dist/index-D7c2WAbn.d.ts +4 -0
- package/dist/layout-Dj3_KscE.js +5 -0
- package/dist/layout.d.ts +3 -0
- package/dist/layout.js +4 -0
- package/dist/{load-Cu7S9GPc.js → load-DWVtW2FC.js} +48 -46
- package/dist/load-DWVtW2FC.js.map +1 -0
- package/dist/load-runtime-config-sUkpYMDx.js +14 -0
- package/dist/load-runtime-config-sUkpYMDx.js.map +1 -0
- package/dist/main.d.ts +2 -1
- package/dist/main.js +8 -8
- package/dist/main.js.map +1 -1
- package/dist/open-file-uploads-B5pr1sA2.js +183 -0
- package/dist/open-file-uploads-B5pr1sA2.js.map +1 -0
- package/dist/package-manager-DWRRy1lv.js +543 -0
- package/dist/package-manager-DWRRy1lv.js.map +1 -0
- package/dist/{pglite-major-B39aOEiE.js → pglite-major-pao-ozRo.js} +23 -5
- package/dist/pglite-major-pao-ozRo.js.map +1 -0
- package/dist/{pglite-migrate-core-Boxqqx-c.js → pglite-migrate-core-B6FqmhH8.js} +9 -7
- package/dist/pglite-migrate-core-B6FqmhH8.js.map +1 -0
- package/dist/{pglite-seed-BqAUvNFw.js → pglite-seed-Ben-06-w.js} +4 -4
- package/dist/{pglite-seed-BqAUvNFw.js.map → pglite-seed-Ben-06-w.js.map} +1 -1
- package/dist/pglite.worker.d.ts +2 -1
- package/dist/pglite.worker.js +4 -3
- package/dist/pglite.worker.js.map +1 -1
- package/dist/pglite.worker.legacy.d.ts +2 -1
- package/dist/pglite.worker.legacy.js +4 -3
- package/dist/pglite.worker.legacy.js.map +1 -1
- package/dist/plugin-configs.d.ts +242 -0
- package/dist/plugin-configs.d.ts.map +1 -0
- package/dist/plugin-configs.js +26 -0
- package/dist/plugin-configs.js.map +1 -0
- package/dist/plugins-BXcwZXcP.js +264 -0
- package/dist/plugins-BXcwZXcP.js.map +1 -0
- package/dist/{preferences-store-_5Cw4_YV.js → preferences-store-DxYAnGCc.js} +6 -25
- package/dist/preferences-store-DxYAnGCc.js.map +1 -0
- package/dist/prerender.d.ts +38 -0
- package/dist/prerender.d.ts.map +1 -0
- package/dist/prerender.js +195 -0
- package/dist/prerender.js.map +1 -0
- package/dist/prerendered-shell-peKE7AqI.js +51 -0
- package/dist/prerendered-shell-peKE7AqI.js.map +1 -0
- package/dist/{pwa-manifest-link-DIgOSo2Q.js → pwa-manifest-link-DNwWvnLV.js} +5 -5
- package/dist/{pwa-manifest-link-DIgOSo2Q.js.map → pwa-manifest-link-DNwWvnLV.js.map} +1 -1
- package/dist/reactor-chat-B0IFAanh.js +15 -0
- package/dist/reactor-chat-B0IFAanh.js.map +1 -0
- package/dist/reactor-wOiLUmuW.js +1639 -0
- package/dist/reactor-wOiLUmuW.js.map +1 -0
- package/dist/reactor.worker.d.ts +2 -1
- package/dist/reactor.worker.js +478 -158
- package/dist/reactor.worker.js.map +1 -1
- package/dist/{registerServiceWorker-BSzbNfvz.js → registerServiceWorker-OR8nokAn.js} +5 -5
- package/dist/{registerServiceWorker-BSzbNfvz.js.map → registerServiceWorker-OR8nokAn.js.map} +1 -1
- package/dist/root-v9fj27sn.js +27 -0
- package/dist/root-v9fj27sn.js.map +1 -0
- package/dist/route-tree.d.ts +2220 -0
- package/dist/route-tree.d.ts.map +1 -0
- package/dist/route-tree.js +135 -0
- package/dist/route-tree.js.map +1 -0
- package/dist/route-views-BovMNHyn.js +60 -0
- package/dist/route-views-BovMNHyn.js.map +1 -0
- package/dist/route-views-C-H3ofJW.js +4 -0
- package/dist/route-views-DzgRMAx8.js +55 -0
- package/dist/route-views-DzgRMAx8.js.map +1 -0
- package/dist/route-views.d.ts +7 -0
- package/dist/route-views.d.ts.map +1 -0
- package/dist/route-views.js +4 -0
- package/dist/router-CWIsjETx.js +54 -0
- package/dist/router-CWIsjETx.js.map +1 -0
- package/dist/router-CnWkTEey.js +4 -0
- package/dist/router.d.ts +2 -0
- package/dist/router.js +3 -0
- package/dist/sentry-Cuc_Nbba.js +22 -0
- package/dist/sentry-Cuc_Nbba.js.map +1 -0
- package/dist/settings-CkNLybyI.js +1089 -0
- package/dist/settings-CkNLybyI.js.map +1 -0
- package/dist/settings-tabs-C0yGKzgj.js +424 -0
- package/dist/settings-tabs-C0yGKzgj.js.map +1 -0
- package/dist/shell-core-head.html +2 -0
- package/dist/shell-core.html +1 -0
- package/dist/shell-head.html +2 -0
- package/dist/shell-plugins.json +1 -0
- package/dist/shell.html +1 -0
- package/dist/start-connect.d.ts +7 -9
- package/dist/start-connect.d.ts.map +1 -1
- package/dist/start-connect.js +9 -8
- package/dist/start-connect.js.map +1 -1
- package/dist/store-lock-Bi3B9VJD.js +159 -0
- package/dist/store-lock-Bi3B9VJD.js.map +1 -0
- package/dist/style.css +3482 -733
- package/dist/{toast-BXIGd4Eb.js → toast-C6WW-_O-.js} +3 -3
- package/dist/{toast-BXIGd4Eb.js.map → toast-C6WW-_O-.js.map} +1 -1
- package/dist/ui-C1-l-Eyh.js +170 -0
- package/dist/ui-C1-l-Eyh.js.map +1 -0
- package/dist/ui-DQrlNYAB.js +66 -0
- package/dist/ui-DQrlNYAB.js.map +1 -0
- package/dist/{use-renown-login-Cf3va6u_.js → use-renown-login-dPpDOYq5.js} +4 -4
- package/dist/use-renown-login-dPpDOYq5.js.map +1 -0
- package/dist/workflows-C3qEvx1R.js +63 -0
- package/dist/workflows-C3qEvx1R.js.map +1 -0
- package/fonts.css +177 -0
- package/generic-routes.json +9 -0
- package/package.json +87 -26
- package/scripts/assert-plugin-configs.mjs +47 -0
- package/scripts/prerender-shell.ts +51 -0
- package/skills/customize-connect/SKILL.md +80 -0
- package/skills/customize-connect/references/data-and-navigation.md +315 -0
- package/skills/customize-connect/references/drive-apps.md +44 -0
- package/skills/customize-connect/references/hosts-and-plugins.md +88 -0
- package/skills/customize-connect/references/layout.md +162 -0
- package/skills/customize-connect/references/modals.md +99 -0
- package/skills/customize-connect/references/overrides.md +177 -0
- package/skills/customize-connect/references/packages.md +41 -0
- package/skills/customize-connect/references/pages.md +141 -0
- package/skills/customize-connect/references/runtime-config.md +403 -0
- package/skills/customize-connect/references/styles-and-branding.md +76 -0
- package/skills/customize-connect/references/types-and-troubleshooting.md +64 -0
- package/src/route-tree.ts +3 -0
- package/src/routeTree.gen.ts +235 -0
- package/src/router/index.ts +2 -0
- package/src/router/register.ts +9 -0
- package/src/routes/__root.tsx +12 -0
- package/src/routes/_app/$.tsx +13 -0
- package/src/routes/_app/d/$driveSlug/{-$nodeSlug}.tsx +13 -0
- package/src/routes/_app/d/$driveSlug.tsx +13 -0
- package/src/routes/_app/index.tsx +13 -0
- package/src/routes/_app/settings/appearance.tsx +13 -0
- package/src/routes/_app/settings/packages.tsx +13 -0
- package/src/routes/_app/settings.tsx +13 -0
- package/src/routes/_app.tsx +13 -0
- package/style.css +8 -23
- package/tailwind.css +12 -0
- package/theme.css +5 -0
- package/dist/AddDriveModal-xAw48kdl.js.map +0 -1
- package/dist/ClearStorageModal-C1BXHTq3.js.map +0 -1
- package/dist/ConfirmDocumentUpgradeModal-FUOhZsk7.js.map +0 -1
- package/dist/CreateDocumentModal-C45W8J0V.js +0 -35
- package/dist/CreateDocumentModal-C45W8J0V.js.map +0 -1
- package/dist/DebugSettingsModal-ClqHzcxM.js.map +0 -1
- package/dist/DeleteDriveModal-Dug84t1j.js.map +0 -1
- package/dist/DeleteItemModal-mMzy3V8o.js.map +0 -1
- package/dist/DisclaimerModal-DvpD5dPM.js.map +0 -1
- package/dist/DocumentVersionUnsupportedModal-C3Q0V75l.js.map +0 -1
- package/dist/DownloadDocumentWithErrorsModal-IKl0ljQb.js.map +0 -1
- package/dist/DriveAuthRequiredModal-DVK7ZQzO.js.map +0 -1
- package/dist/DriveSettingsModal-C6-mRQiv.js +0 -57
- package/dist/DriveSettingsModal-C6-mRQiv.js.map +0 -1
- package/dist/InspectorModal-7FQBTEzt.js.map +0 -1
- package/dist/LoginModal-CybbOm3N.js.map +0 -1
- package/dist/MissingPackageModal-nBnExqO0.js +0 -49
- package/dist/MissingPackageModal-nBnExqO0.js.map +0 -1
- package/dist/OpenFileDocumentsModal-DGaYJpXW.js.map +0 -1
- package/dist/SettingsModal-CPv3_jmp.js +0 -569
- package/dist/SettingsModal-CPv3_jmp.js.map +0 -1
- package/dist/UpgradeDriveModal-_8t9slxQ.js.map +0 -1
- package/dist/app-loader-C4pFYc82.js +0 -4
- package/dist/app-loader-DyGcBhGV.js +0 -2244
- package/dist/app-loader-DyGcBhGV.js.map +0 -1
- package/dist/build-info-D9_h0032.js.map +0 -1
- package/dist/components-MEmS6hgr.js +0 -4
- package/dist/connect.config-DaHDEUrw.js.map +0 -1
- package/dist/connection-state-3w4liC1X.js.map +0 -1
- package/dist/load-Cu7S9GPc.js.map +0 -1
- package/dist/pglite-major-B39aOEiE.js.map +0 -1
- package/dist/pglite-migrate-core-Boxqqx-c.js.map +0 -1
- package/dist/preferences-store-_5Cw4_YV.js.map +0 -1
- package/dist/reactor-yC8BveHb.js +0 -1464
- package/dist/reactor-yC8BveHb.js.map +0 -1
- package/dist/runtime-config-DL3QjcfM.js +0 -24
- package/dist/runtime-config-DL3QjcfM.js.map +0 -1
- package/dist/sentry-QXKgQmr2.js +0 -15
- package/dist/sentry-QXKgQmr2.js.map +0 -1
- package/dist/use-renown-login-Cf3va6u_.js.map +0 -1
- package/dist/useRegistryPackages-BnUcL_nZ.js +0 -390
- package/dist/useRegistryPackages-BnUcL_nZ.js.map +0 -1
|
@@ -0,0 +1,403 @@
|
|
|
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
|
+
## Contents
|
|
6
|
+
|
|
7
|
+
- [TL;DR](#tldr)
|
|
8
|
+
- [The file](#the-file): [Renown sign-in](#renown-in-page-sign-in-connectrenownswitchboardurl--adapters), [reactor flags](#reactor-enforcement-flags-connectreactorfeatureflags), [creation signature policy](#creation-signature-policy-connectreactorcreatesignaturepolicy), [unsupported stored documents](#stored-documents-this-build-does-not-run-connectreactorunsupportedstoreddocuments), [multi-reactor routing](#multi-reactor-routing-connectinstancemultireactor)
|
|
9
|
+
- [Setting values — the precedence ladder](#setting-values--the-precedence-ladder): [five ways to feed a value](#the-five-ways-to-feed-a-value-into-a-layer), [notes on each method](#notes-on-each-method)
|
|
10
|
+
- [How Connect reads the file at boot](#how-connect-reads-the-file-at-boot)
|
|
11
|
+
- [Other consumers of the same file](#other-consumers-of-the-same-file)
|
|
12
|
+
- [Common operator workflows](#common-operator-workflows)
|
|
13
|
+
- [Design principle, in one line](#design-principle-in-one-line)
|
|
14
|
+
|
|
15
|
+
## TL;DR
|
|
16
|
+
|
|
17
|
+
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.
|
|
18
|
+
|
|
19
|
+
```
|
|
20
|
+
┌──────────── ways to set a value ────────────┐
|
|
21
|
+
│
|
|
22
|
+
ph init (scaffold defaults) │
|
|
23
|
+
edit powerhouse.config.json by hand │
|
|
24
|
+
ph connect config --<field> <value> │
|
|
25
|
+
ph connect build --<field> <value> │
|
|
26
|
+
ph install --registry <url> │
|
|
27
|
+
PH_CONNECT_CONFIG_JSON env (deploy-time) │
|
|
28
|
+
│
|
|
29
|
+
└──────────────────────┬───────────────────────┘
|
|
30
|
+
│
|
|
31
|
+
▼
|
|
32
|
+
powerhouse.config.json (dist)
|
|
33
|
+
│
|
|
34
|
+
│ fetch('/powerhouse.config.json')
|
|
35
|
+
▼
|
|
36
|
+
Connect SPA — ConfigLoader cached at boot
|
|
37
|
+
│
|
|
38
|
+
getRuntimeConfig() / getConnectConfig()
|
|
39
|
+
▼
|
|
40
|
+
consumed by Package Manager, Renown,
|
|
41
|
+
drive sidebar, router basename, etc.
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## The file
|
|
45
|
+
|
|
46
|
+
Schema lives in `packages/builder-tools/connect-utils/runtime-config-schema.ts`. Shape (simplified):
|
|
47
|
+
|
|
48
|
+
```jsonc
|
|
49
|
+
{
|
|
50
|
+
"$schema": "...",
|
|
51
|
+
"schemaVersion": 2,
|
|
52
|
+
|
|
53
|
+
// Top-level — project-wide, also read by ph-cli + Switchboard:
|
|
54
|
+
"packages": [
|
|
55
|
+
{ "packageName": "@scope/pkg", "version": "1.0.0", "provider": "registry" }
|
|
56
|
+
],
|
|
57
|
+
"packageRegistryUrl": "https://registry.vetra.io",
|
|
58
|
+
"localPackage": { "name": "...", "version": "..." } | null,
|
|
59
|
+
|
|
60
|
+
// Connect-only runtime values:
|
|
61
|
+
"connect": {
|
|
62
|
+
"branding": { "appName": "...", "icon": "..." | null, "loader": "..." | { src, animation, size } | null },
|
|
63
|
+
"home": { "background": "..." | { color, layers: [{ src, position, width, height, fade, ... }] } | null },
|
|
64
|
+
"app": { "logLevel": "info", "basePath": "/", "offline": true },
|
|
65
|
+
"renown": { "url": "...", "networkId": "eip155", "chainId": 1, "switchboardUrl": "..." | undefined, "adapters": {...} | undefined },
|
|
66
|
+
"drives": { "allowAddDrive": true, "defaultDrives": [...], "preserveStrategy": "...", "sections": {...},
|
|
67
|
+
"icons": { localDrive, remoteDrive, folder, document, documents } | null },
|
|
68
|
+
"packages": { "externalEnabled": true },
|
|
69
|
+
"sentry": { "dsn": null, "env": "dev", "tracing": false },
|
|
70
|
+
"openPanel": { "clientId": "", "apiUrl": "..." | undefined, "trackUiEvents": true, "trackOperations": true },
|
|
71
|
+
"reactor": { "featureFlags": { "documentDecisions": false, "authEnforcement": false, "authGroups": false, "authConditions": false }, "createSignaturePolicy": "v2-required", "unsupportedStoredDocuments": "refuse" },
|
|
72
|
+
"pwa": { ... } // build-time only, see below
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
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.
|
|
78
|
+
|
|
79
|
+
### Renown in-page sign-in (`connect.renown.switchboardUrl` + `adapters`)
|
|
80
|
+
|
|
81
|
+
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.
|
|
82
|
+
|
|
83
|
+
`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 "Wallet adapters (in-page sign-in)" in the `@renown/sdk` README.) Connect's config-to-adapter mapping lives in `src/components/renown-adapter-descriptors.ts`.
|
|
84
|
+
|
|
85
|
+
```jsonc
|
|
86
|
+
"renown": {
|
|
87
|
+
"url": "https://www.renown.id", // redirect fallback
|
|
88
|
+
"switchboardUrl": "https://switchboard.example/graphql", // enables in-page auth
|
|
89
|
+
"adapters": {
|
|
90
|
+
"rainbow": { "walletConnectProjectId": "..." }, // external wallets
|
|
91
|
+
"privy": { "appId": "...", "methods": ["google", "email"] } // social / email
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
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.
|
|
97
|
+
|
|
98
|
+
`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`.
|
|
99
|
+
|
|
100
|
+
`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.
|
|
101
|
+
|
|
102
|
+
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`.
|
|
103
|
+
|
|
104
|
+
### Reactor enforcement flags (`connect.reactor.featureFlags`)
|
|
105
|
+
|
|
106
|
+
The reactor Connect runs in the browser takes the same four enforcement flags a
|
|
107
|
+
switchboard does: `documentDecisions`, `authEnforcement`, `authGroups`,
|
|
108
|
+
`authConditions`. Each requires the one before it, and the reactor refuses to
|
|
109
|
+
build a set that skips one. All default `false`.
|
|
110
|
+
|
|
111
|
+
```jsonc
|
|
112
|
+
"reactor": {
|
|
113
|
+
"featureFlags": {
|
|
114
|
+
"documentDecisions": true,
|
|
115
|
+
"authEnforcement": true,
|
|
116
|
+
"authGroups": true,
|
|
117
|
+
"authConditions": true
|
|
118
|
+
}
|
|
119
|
+
}
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
These are the one part of `connect.*` that is not a local preference. A flag
|
|
123
|
+
changes how stored history is replayed, and a replay verdict is a consensus
|
|
124
|
+
outcome, so **a Connect must carry the same flags as the fleet it syncs with**.
|
|
125
|
+
A flags-off Connect syncing an enforcing switchboard applies operations that
|
|
126
|
+
switchboard denied and the two diverge. Set them per fleet, alongside the
|
|
127
|
+
switchboard's `REACTOR_*` env vars (see `apps/switchboard/README.md`).
|
|
128
|
+
|
|
129
|
+
Both reactor hosts read them: the main-thread reactor takes the value from this
|
|
130
|
+
file directly, and the SharedWorker gets it in its construct message, for the
|
|
131
|
+
same reason it gets `renown.chainId` — a worker has no runtime config of its
|
|
132
|
+
own. There is deliberately no query-param or localStorage override, unlike
|
|
133
|
+
`connect.instance.reactorWorker`: a per-tab flag would be a per-node flag.
|
|
134
|
+
|
|
135
|
+
The flag set is part of the worker's version fingerprint, so a flip is picked up
|
|
136
|
+
even though it isn't a rebuild. A tab whose flags differ from the running
|
|
137
|
+
worker's is told to reload onto a fresh worker, exactly as it would be after a
|
|
138
|
+
new build — without that, the worker would keep enforcing the flags it booted
|
|
139
|
+
with while the tab believed the new set was live. Other tabs still on the old
|
|
140
|
+
worker reload as they refresh.
|
|
141
|
+
|
|
142
|
+
With `authEnforcement` on, both hosts install the Renown trust policy that
|
|
143
|
+
switchboard installs under `REACTOR_AUTH_ENFORCEMENT`: a signed write is
|
|
144
|
+
accepted when a Renown credential binds its key to the wallet it claims, and
|
|
145
|
+
the logged-in user's own key is accepted without a lookup. Credentials are
|
|
146
|
+
read from `connect.renown.switchboardUrl`, or the switchboard `connect.renown.url`
|
|
147
|
+
advertises, else Renown's REST API at `connect.renown.url`, so that endpoint must
|
|
148
|
+
be reachable from the browser. With neither set, the reactor fails to build
|
|
149
|
+
rather than refuse every signed write. The worker gets both URLs in its construct
|
|
150
|
+
message and keeps the ones the first tab booted it with.
|
|
151
|
+
|
|
152
|
+
### Creation signature policy (`connect.reactor.createSignaturePolicy`)
|
|
153
|
+
|
|
154
|
+
What the documents and drives Connect creates are born as: `"v2-required"`
|
|
155
|
+
(the default) or `"legacy"`. A v2-required document accepts only v2 action
|
|
156
|
+
signatures and takes a content-addressed id. Set `"legacy"` while any reactor
|
|
157
|
+
Connect syncs with predates v2-required documents; existing documents keep
|
|
158
|
+
their policy either way, and the setting does not change what Connect accepts.
|
|
159
|
+
|
|
160
|
+
```jsonc
|
|
161
|
+
"reactor": { "createSignaturePolicy": "legacy" }
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
The main-thread reactor reads it from this file; the SharedWorker gets it in its
|
|
165
|
+
construct message and keeps the value the first tab booted it with. It is not
|
|
166
|
+
part of the worker's version fingerprint.
|
|
167
|
+
|
|
168
|
+
### Stored documents this build does not run (`connect.reactor.unsupportedStoredDocuments`)
|
|
169
|
+
|
|
170
|
+
A reactor refuses to boot when the browser's store holds documents created at a
|
|
171
|
+
protocol version the build does not run, for example after rolling Connect back
|
|
172
|
+
to a release that predates one. Connect then shows "Connect cannot open this
|
|
173
|
+
browser's documents" with the versions and document count, instead of the app.
|
|
174
|
+
There are two ways forward: serve a Connect build that runs those versions, or
|
|
175
|
+
accept them read-only:
|
|
176
|
+
|
|
177
|
+
```jsonc
|
|
178
|
+
"reactor": { "unsupportedStoredDocuments": "read-only" }
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
`"refuse"` is the default. With `"read-only"` the reactor boots, logs a warning,
|
|
182
|
+
and refuses every write into those documents and every operation received for
|
|
183
|
+
them; the rest of the store works as usual. Connect has no in-app button for it:
|
|
184
|
+
the setting is the operator's choice, so it goes in this file (or
|
|
185
|
+
`PH_CONNECT_CONFIG_JSON`), and the boot screen's Reload picks up the change.
|
|
186
|
+
Both reactor hosts read it; the SharedWorker gets it in its construct message.
|
|
187
|
+
A worker that refused retries the build on the next tab's connect, so the new
|
|
188
|
+
value takes effect without closing other tabs.
|
|
189
|
+
|
|
190
|
+
### Multi-reactor routing (`connect.instance.multiReactor`)
|
|
191
|
+
|
|
192
|
+
Experimental, optional, default `false`. When on, Connect reads and writes
|
|
193
|
+
through a router over its own reactor and the Switchboard of the first remote
|
|
194
|
+
default drive (`drives.defaultDrives[].url`), and its reactor gains a local sync
|
|
195
|
+
channel.
|
|
196
|
+
|
|
197
|
+
```jsonc
|
|
198
|
+
"instance": { "multiReactor": true }
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
It is part of the worker's version fingerprint, so like the enforcement flags
|
|
202
|
+
it is set in this file only, with no query-param or localStorage override.
|
|
203
|
+
|
|
204
|
+
## Setting values — the precedence ladder
|
|
205
|
+
|
|
206
|
+
When `ph connect build` runs, the _dist_ `powerhouse.config.json` is produced by deep-merging in this order (lowest → highest):
|
|
207
|
+
|
|
208
|
+
```
|
|
209
|
+
DEFAULT_CONNECT_CONFIG < source.connect < CLI flag overrides
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
Plus the top-level field:
|
|
213
|
+
|
|
214
|
+
```
|
|
215
|
+
packageRegistryUrl = cliPackageRegistryUrl ?? source.packageRegistryUrl ?? null
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
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".
|
|
219
|
+
|
|
220
|
+
Two fields interact with the service worker and deserve a caveat:
|
|
221
|
+
|
|
222
|
+
- **`connect.branding.favicon` is build-time only.** A file relative to the project, served by `ph connect studio` and built by `ph connect build` as `icon.ico`, `icon.svg` or `icon.png`, keeping its type; the dist file leaves it out.
|
|
223
|
+
- **`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.
|
|
224
|
+
- **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.
|
|
225
|
+
- **`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.
|
|
226
|
+
|
|
227
|
+
### The five ways to feed a value into a layer
|
|
228
|
+
|
|
229
|
+
| Way | Lands in | When to use |
|
|
230
|
+
| ----------------------------------------------------------- | ----------------------------------------------- | -------------------------------------------------------------------- |
|
|
231
|
+
| `ph init` template | source file | Initial scaffold; gives every project a working default |
|
|
232
|
+
| Manual edit of `<project>/powerhouse.config.json` | source file | Local dev tweaks; checked into git |
|
|
233
|
+
| `ph connect config --<field> <value>` (or `--json '{...}'`) | source **and** dist (dual-write) | Quick CLI edit that takes effect on next refresh, without rebuilding |
|
|
234
|
+
| `ph connect build --<field> <value>` (or `--json '{...}'`) | dist (CLI override layer) | One-off override at build time, e.g. CI baking a different `--base` |
|
|
235
|
+
| Docker entrypoint env var `PH_CONNECT_CONFIG_JSON` | dist file at container start, **operator-wins** | Per-deployment knobs without rebuilding the image |
|
|
236
|
+
|
|
237
|
+
Two special-case writers also exist:
|
|
238
|
+
|
|
239
|
+
- `ph install --registry <url>` writes the top-level `packageRegistryUrl` (overwrites when `--registry` is explicit, otherwise preserves existing).
|
|
240
|
+
- `ph vetra` passes a programmatic `callerOverride` to `ph connect studio` so default drives don't have to be tipped on every invocation. It also sets `instance.reactorClient: "remote"`, so Studio reads and writes every drive on the local Switchboard (drives created in Studio land there too), unless the project sets `instance.multiReactor` or `instance.reactorClient`, or runs `ph vetra --remote-drive`. `ph migrate` drops the `connect.instance` block older scaffolds wrote.
|
|
241
|
+
|
|
242
|
+
### Notes on each method
|
|
243
|
+
|
|
244
|
+
**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.
|
|
245
|
+
|
|
246
|
+
**`ph connect config`.** Four modes (mutually exclusive — positional, `--get`, `--json`, and field flags cannot be combined):
|
|
247
|
+
|
|
248
|
+
- No args → list mode: prints the effective `connect.*` block (defaults + source).
|
|
249
|
+
- `<key>` (positional) or `--get <dotted.path>` → prints a single value at the dotted path (also works for top-level `packageRegistryUrl`).
|
|
250
|
+
- `<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.
|
|
251
|
+
- `--json '{...}'` → bulk-set mode: validates the full patch and dual-writes.
|
|
252
|
+
|
|
253
|
+
**`--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.
|
|
254
|
+
|
|
255
|
+
```bash
|
|
256
|
+
# Enables workflows and adds a default drive.
|
|
257
|
+
ph connect build --json '{"app":{"workflowsEnabled":true},"drives":{"defaultDrives":[{"url":"http://localhost:4001/d/my-workflows","name":"My workflows"}]}}'
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
**`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>`.
|
|
261
|
+
|
|
262
|
+
**`--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`.
|
|
263
|
+
|
|
264
|
+
**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.
|
|
265
|
+
|
|
266
|
+
```bash
|
|
267
|
+
docker run \
|
|
268
|
+
-e PH_CONNECT_CONFIG_JSON='{"connect":{"renown":{"url":"https://renown.staging"},"app":{"logLevel":"debug"}}}' \
|
|
269
|
+
connect:latest
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
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.
|
|
273
|
+
|
|
274
|
+
## How Connect reads the file at boot
|
|
275
|
+
|
|
276
|
+
`apps/connect/main.tsx`:
|
|
277
|
+
|
|
278
|
+
```tsx
|
|
279
|
+
import { createRoot } from "react-dom/client";
|
|
280
|
+
import { loadRuntimeConfig } from "./src/runtime-config.js";
|
|
281
|
+
|
|
282
|
+
if (!window.ph) window.ph = {};
|
|
283
|
+
|
|
284
|
+
// Bootstrap the runtime config BEFORE AppLoader's transitive imports
|
|
285
|
+
await loadRuntimeConfig();
|
|
286
|
+
const { AppLoader } = await import("./src/components/app-loader.js");
|
|
287
|
+
|
|
288
|
+
createRoot(document.getElementById("root")!).render(<AppLoader />);
|
|
289
|
+
```
|
|
290
|
+
|
|
291
|
+
Two ordering tricks:
|
|
292
|
+
|
|
293
|
+
1. **Top-level await** on `loadRuntimeConfig()` blocks module evaluation until the fetch resolves.
|
|
294
|
+
2. **Dynamic import** of `AppLoader` so any module that calls `getRuntimeConfig()` at import time (synchronous read from the cache) only runs _after_ step 1.
|
|
295
|
+
|
|
296
|
+
Together these prevent a cache-empty race where the SPA would have to fall back to defaults or throw.
|
|
297
|
+
|
|
298
|
+
`loadRuntimeConfig` (in `apps/connect/src/runtime-config.ts`) is a 4-line wrapper around the shared loader:
|
|
299
|
+
|
|
300
|
+
```ts
|
|
301
|
+
const loader = new ConfigLoader(
|
|
302
|
+
new JsonConfigAdapter({
|
|
303
|
+
path: `${import.meta.env.BASE_URL}powerhouse.config.json`,
|
|
304
|
+
}),
|
|
305
|
+
);
|
|
306
|
+
```
|
|
307
|
+
|
|
308
|
+
- `ConfigLoader` (in `packages/shared/connect/config-loader.ts`) wraps any `ConfigAdapter` with deep-merge-against-defaults and in-process caching.
|
|
309
|
+
- `JsonConfigAdapter` reads via `fetch()` when `window` is defined, via `fs` in Node.
|
|
310
|
+
- After `loadRuntimeConfig()` resolves once, any synchronous `getRuntimeConfig()` call returns the cached payload immediately.
|
|
311
|
+
|
|
312
|
+
Downstream consumers inside the SPA:
|
|
313
|
+
|
|
314
|
+
| File | Reads |
|
|
315
|
+
| ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
316
|
+
| `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 |
|
|
317
|
+
| `apps/connect/src/hooks/useRegistryPackages.ts` | `getRuntimeConfig().packageRegistryUrl` |
|
|
318
|
+
| `apps/connect/src/store/reactor.ts` | Passes `packageRegistryUrl` to `BrowserPackageManager`; reads `connect.reactor.featureFlags`, `createSignaturePolicy` and `unsupportedStoredDocuments` for both reactor hosts |
|
|
319
|
+
| Renown auth flow | Reads `connect.renown.*` |
|
|
320
|
+
| Drives sidebar | Reads `connect.drives.*` |
|
|
321
|
+
| Router | Reads `connect.app.basePath` |
|
|
322
|
+
| `apps/connect/src/components/app.tsx` | Reads `connect.app.offline` to register or unregister the service worker |
|
|
323
|
+
|
|
324
|
+
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.
|
|
325
|
+
|
|
326
|
+
## Other consumers of the same file
|
|
327
|
+
|
|
328
|
+
The dist `powerhouse.config.json` is not a Connect-private artefact:
|
|
329
|
+
|
|
330
|
+
- **Switchboard** (Node) reads `packages[]` and `packageRegistryUrl` at startup via the same `ConfigLoader` + `JsonConfigAdapter` (Node branch).
|
|
331
|
+
- **`ph install` / `ph publish`** use `resolveRegistryUrl` to pick a registry with priority `--flag > PH_REGISTRY_URL env > config.packageRegistryUrl > DEFAULT_REGISTRY_URL`.
|
|
332
|
+
|
|
333
|
+
This is why `packageRegistryUrl` lives at the top level rather than nested under `connect.*` — it's a project-wide setting, not Connect-only.
|
|
334
|
+
|
|
335
|
+
## Common operator workflows
|
|
336
|
+
|
|
337
|
+
**"I just want to point Connect at a different registry."**
|
|
338
|
+
Edit the project's `powerhouse.config.json`, set `"packageRegistryUrl": "https://my.registry"`, refresh Connect. Or `ph connect config --packages-registry https://my.registry`.
|
|
339
|
+
|
|
340
|
+
**"I want a subpath deploy (`/connect` instead of `/`)."**
|
|
341
|
+
`ph connect build --base /connect`. The CLI override lands in the dist `connect.app.basePath` and the bundled assets pick it up.
|
|
342
|
+
|
|
343
|
+
**"I want default drives to load automatically."**
|
|
344
|
+
`ph connect config --default-drives-url https://drive-a, https://drive-b`. The CSV is parsed into `connect.drives.defaultDrives[]` objects.
|
|
345
|
+
|
|
346
|
+
**"I want my project to boot with a preconfigured local drive."**
|
|
347
|
+
Add a local entry to `connect.drives.defaultDrives` in `powerhouse.config.json`:
|
|
348
|
+
`{"local": true, "id": "my-drive", "name": "My Drive", "icon": "https://…", "app": "powerhouse/generic-drive-explorer"}`.
|
|
349
|
+
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.
|
|
350
|
+
|
|
351
|
+
**"I'm deploying the docker image to a new environment and need to override renown."**
|
|
352
|
+
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.
|
|
353
|
+
|
|
354
|
+
**"I need a different Sentry DSN per environment."**
|
|
355
|
+
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:
|
|
356
|
+
|
|
357
|
+
```bash
|
|
358
|
+
docker run -e PH_CONNECT_CONFIG_JSON='{
|
|
359
|
+
"connect": {
|
|
360
|
+
"sentry": { "dsn": "https://prod-key@sentry.io/1", "env": "prod", "tracing": true }
|
|
361
|
+
}
|
|
362
|
+
}' connect:latest
|
|
363
|
+
```
|
|
364
|
+
|
|
365
|
+
`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.
|
|
366
|
+
|
|
367
|
+
**"I want OpenPanel analytics on this deployment."**
|
|
368
|
+
Set `connect.openPanel.clientId` (and `apiUrl` for a self-hosted OpenPanel):
|
|
369
|
+
|
|
370
|
+
```bash
|
|
371
|
+
docker run -e PH_CONNECT_CONFIG_JSON='{
|
|
372
|
+
"connect": {
|
|
373
|
+
"openPanel": { "clientId": "<client-id>", "apiUrl": "https://openpanel.example/api" }
|
|
374
|
+
}
|
|
375
|
+
}' connect:latest
|
|
376
|
+
```
|
|
377
|
+
|
|
378
|
+
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.
|
|
379
|
+
|
|
380
|
+
**"I'm turning auth enforcement on for this fleet."**
|
|
381
|
+
Set the whole flag set on the container, matching the switchboard's `REACTOR_*` env vars exactly:
|
|
382
|
+
|
|
383
|
+
```bash
|
|
384
|
+
docker run -e PH_CONNECT_CONFIG_JSON='{
|
|
385
|
+
"connect": {
|
|
386
|
+
"reactor": { "featureFlags": {
|
|
387
|
+
"documentDecisions": true, "authEnforcement": true,
|
|
388
|
+
"authGroups": true, "authConditions": true
|
|
389
|
+
} }
|
|
390
|
+
}
|
|
391
|
+
}' connect:latest
|
|
392
|
+
```
|
|
393
|
+
|
|
394
|
+
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").
|
|
395
|
+
|
|
396
|
+
**"I want to verify what Connect will actually use without booting it."**
|
|
397
|
+
`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.
|
|
398
|
+
|
|
399
|
+
Adding or changing a `connect.*` field is work in the Powerhouse monorepo; its steps are in `apps/connect/CUSTOMIZING.md` there.
|
|
400
|
+
|
|
401
|
+
## Design principle, in one line
|
|
402
|
+
|
|
403
|
+
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).
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
# Styles and branding
|
|
2
|
+
|
|
3
|
+
## Styles
|
|
4
|
+
|
|
5
|
+
A project's styles are in two files, which the page builds as one Tailwind build:
|
|
6
|
+
|
|
7
|
+
- `style.css`, at the root, is the package's: Connect's imports, then the tokens and rules the package's editors and routes use. `ph build` ships it as the package's stylesheet (see [A package's styles](#a-packages-styles)).
|
|
8
|
+
- `hosts/connect/style.css` is this Connect's: its theme and global rules. The host's build adds it after `style.css`; `ph build` never reads it, so it reaches no other Connect.
|
|
9
|
+
|
|
10
|
+
```css
|
|
11
|
+
/* style.css */
|
|
12
|
+
@layer properties, theme, base, components, external-packages, utilities;
|
|
13
|
+
@import "tailwindcss";
|
|
14
|
+
@import "@powerhousedao/connect/tailwind.css";
|
|
15
|
+
|
|
16
|
+
/* A token the package's editors use. */
|
|
17
|
+
@theme {
|
|
18
|
+
--color-brand: #f60;
|
|
19
|
+
}
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
```css
|
|
23
|
+
/* hosts/connect/style.css */
|
|
24
|
+
@theme static {
|
|
25
|
+
--color-red-700: #b42318;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/* A semantic token: set its light value and its dark one. */
|
|
29
|
+
:root {
|
|
30
|
+
--primary: #0a5bc4;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
:root.dark {
|
|
34
|
+
--primary: #6aa8ff;
|
|
35
|
+
--background: #16181c;
|
|
36
|
+
}
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
- `@powerhousedao/connect/tailwind.css` brings the design system's tokens, core's theme, Connect's own rules and the `@source` lines for the classes Connect's code uses. Tailwind generates those classes in the project's build, next to the project's own.
|
|
40
|
+
- One build means one copy of each utility, in one `utilities` layer, ordered by Tailwind. Importing a second build (`@powerhousedao/connect/style.css`, or a package's `dist/style.css` built before packages left Connect's classes out) emits the utilities again in source order, so a later `.px-3` beats an earlier `.pl-7`.
|
|
41
|
+
- Third-party CSS (toasts, the JSON viewer, the workflow canvas) comes in through `vendor.css` files: plain rules that Tailwind passes through.
|
|
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.
|
|
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.
|
|
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.
|
|
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, and creates `hosts/connect/style.css` when it is missing (a host with its own `runner.routes` creates its file by hand). It moves Connect's theme out of `style.css`: declarations of the design system's and core's semantic tokens (`--primary`, `--ring`, `--ph-core-bg`, ...) on `:root`, `html`, `.dark` or `[data-theme]` go to `hosts/connect/style.css`, and the package's own tokens stay. It moves them only when the host's file is new or still the empty template, and only top-level rules whose selectors are all theme selectors; otherwise it leaves them and warns, naming each rule and token. It also warns about `html` and `body` rules, which ship with the package too.
|
|
47
|
+
|
|
48
|
+
## A package's styles
|
|
49
|
+
|
|
50
|
+
`ph build` writes a package's stylesheet, `dist/style.css`, from the root `style.css`. It holds the package's own classes and rules, without Tailwind's reset or Connect's classes, since the Connect that loads the package has those:
|
|
51
|
+
|
|
52
|
+
- Tailwind's theme and `@powerhousedao/connect/theme.css` come in by `@reference`. The package's classes can use Connect's tokens, variants and plugins (`bg-background`, `text-core-fg`, `dark:`, `scrollbar-thin`), and the build emits none of them. The classes read the tokens from the page; palette and spacing classes fall back to the referenced values.
|
|
53
|
+
- Tailwind scans the package's browser build (`dist/browser`), so only code that ships adds classes: not host-only routes such as `_app.tsx`, nor components the bundle leaves out.
|
|
54
|
+
- The options of the project's `@import "tailwindcss"` carry over, `prefix(...)` and `important` among them; `source(...)` and `theme(...)` don't, since the build sets both.
|
|
55
|
+
- The rest of `style.css` goes in as written: the package's `@theme` tokens, `@utility` definitions and plain rules. A token or rule set here reaches every Connect that loads the package, so keep a Connect's theme in its host file.
|
|
56
|
+
- The file is in the `external-packages` layer: above Connect's reset, so it styles the package's editors, and below Connect's utilities. It declares Connect's layer order first, so the order holds whichever stylesheet the page loads first.
|
|
57
|
+
- Connect loads the stylesheet with the package: from the registry's CDN for a registry package, and with the package's code for a bundled one (`ph install --local`). `style.css` imports no packages.
|
|
58
|
+
- A bundled package is not added to the project's build with `@source`. Its tokens, `@utility` definitions and rules live in its own `style.css`, which the project's build doesn't read, and the package renders as it does from the registry.
|
|
59
|
+
|
|
60
|
+
## Name and icon per host
|
|
61
|
+
|
|
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` restarts Studio when `powerhouse.config.json` changes, and the open tab reloads. Inside an editor, the `ph-default-styles` wrapper styles inputs, buttons, selects, checkboxes and radios; utility classes on an element win. A host overrides either in its `config`:
|
|
63
|
+
|
|
64
|
+
```js
|
|
65
|
+
// hosts/lab/host.js
|
|
66
|
+
export default {
|
|
67
|
+
name: "lab",
|
|
68
|
+
runner: { module: "@powerhousedao/ph-cli/runners/connect" },
|
|
69
|
+
config: { branding: { appName: "Lab", favicon: "hosts/lab/icon.svg" } },
|
|
70
|
+
};
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
- A host's `config` merges over the project's `connect` block field by field, so a host inherits what it doesn't set.
|
|
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.
|
|
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`.
|
|
76
|
+
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# Types, troubleshooting and upgrading
|
|
2
|
+
|
|
3
|
+
## Types
|
|
4
|
+
|
|
5
|
+
The build generates `.ph/connect-routes.gen.ts`: the route tree of Connect's routes and the project's. It registers the router type, so `createFileRoute` ids, `Link`, `useNavigate`, loader data and search params are typed.
|
|
6
|
+
|
|
7
|
+
- `ph connect build`, `ph connect studio`, `ph connect preview` and `ph build` generate it. `ph connect studio` regenerates it as route files change.
|
|
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
|
+
- 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
|
+
- `ph connect build` type-checks the routes and fails on errors. `--ignore-type-errors` skips the check.
|
|
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
|
+
|
|
13
|
+
## Troubleshooting
|
|
14
|
+
|
|
15
|
+
| Symptom | Cause |
|
|
16
|
+
| --- | --- |
|
|
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
|
+
| `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
|
+
| `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
|
+
| 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
|
+
| 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`. |
|
|
22
|
+
| A route's search param is gone after navigating | Only global params survive a navigation. Pass the param in `search` on the link. |
|
|
23
|
+
| A loader sees no drive on a deep link | The drive has not arrived yet; see [Load data](./data-and-navigation.md#load-data). |
|
|
24
|
+
| A class has no effect, e.g. `pl-7` next to `px-3` | `style.css` imports a second Tailwind build, such as `@powerhousedao/connect/style.css`. Import `@powerhousedao/connect/tailwind.css` instead, or run `ph migrate`; see [Styles](./styles-and-branding.md#styles). |
|
|
25
|
+
| A package's `dist/style.css` is hundreds of KB, or a host's `@theme` values revert to the defaults once the package loads | The package was built before packages left Connect's CSS out: its stylesheet is a full Tailwind build, whose tokens outrank the host's. Rebuild it with `ph build` and publish it; see [A package's styles](./styles-and-branding.md#a-packages-styles). |
|
|
26
|
+
| A package's token or rule works in its own Connect but not in another | It is in `hosts/connect/style.css`, which `ph build` leaves out. Move what the package's editors and routes need to `style.css`. |
|
|
27
|
+
| 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
|
+
| 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` moves Connect's token overrides, or warns about what it can't move. |
|
|
29
|
+
| `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. |
|
|
30
|
+
| 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. |
|
|
31
|
+
|
|
32
|
+
## Upgrading
|
|
33
|
+
|
|
34
|
+
`ph migrate` updates a project for this version:
|
|
35
|
+
|
|
36
|
+
- `style.css` imports `@powerhousedao/connect/tailwind.css` instead of `@powerhousedao/design-system/theme.css` and `@powerhousedao/connect/style.css`. The project's own rules stay.
|
|
37
|
+
- `tsconfig.json` includes `.ph/connect-routes.gen.ts`, the generated tree that types the project's routes.
|
|
38
|
+
- `style.css` drops the `@import './node_modules/<package>/dist/style.css'` lines that `ph install --local` added. Connect loads a bundled package's stylesheet with its code.
|
|
39
|
+
- `hosts/connect/style.css` holds this Connect's theme; `ph migrate` creates it. A project that themed Connect in `style.css` (`--primary` on `:root` and `.dark`, say) re-themes every Connect that installs its package until the overrides move. `ph migrate` moves Connect's token overrides there when the host's file is new or empty, and otherwise warns with the rules and tokens to move by hand; see [Styles](./styles-and-branding.md#styles).
|
|
40
|
+
- A Tailwind host that imported `@powerhousedao/connect-core/theme.css` for core's classes imports `@powerhousedao/connect-core/tailwind.css`. `theme.css` now holds only core's tokens. `@powerhousedao/connect/tailwind.css` does this already.
|
|
41
|
+
|
|
42
|
+
A package rebuilt with `ph build` ships only its own classes and rules (see [A package's styles](./styles-and-branding.md#a-packages-styles)). Republish packages so the Connects that load them keep one Tailwind build per page.
|
|
43
|
+
|
|
44
|
+
Two `@powerhousedao/reactor-browser` types lost a member, which a project that used them updates by hand:
|
|
45
|
+
|
|
46
|
+
- `PHModal` has no `missingPackage` modal.
|
|
47
|
+
- `PHGlobal` has no `revisionHistoryVisible`. `useRevisionHistoryVisible`, `showRevisionHistory` and `hideRevisionHistory` work as before.
|
|
48
|
+
|
|
49
|
+
Editors receive `document` and `dispatch` as props. For TypeScript users this is breaking:
|
|
50
|
+
|
|
51
|
+
- `EditorModule`'s type parameters are now `<TDocument, TAction, TProps>`. A module typed `EditorModule<{ ...props }>` moves its props to the third parameter.
|
|
52
|
+
- A host that renders an `EditorModule`'s `Component` must pass `document` and `dispatch`, and should wrap it in `EditorDocumentProvider` (see [Render an editor or a drive app yourself](./data-and-navigation.md#render-an-editor-or-a-drive-app-yourself)).
|
|
53
|
+
- An editor whose component takes only its own props must share one with what hosts pass (`documentId`, `context`, `displayToolbar`), or take `EditorProps`.
|
|
54
|
+
- `ph generate` writes editors that read `document` and `dispatch` from props. A package with such an editor needs a Connect with this change: older Connects pass neither prop. Editors that use the `useSelected<Model>Document()` hooks keep working in every Connect.
|
|
55
|
+
|
|
56
|
+
In 6.2.3 dev prereleases only, `RouteSelection` and scoped PH stores (`createScopedPHStore`, `isScopedPHStore`) are gone. Drive apps read the route through `DriveProvider`, editors through `EditorDocumentProvider`, both from `@powerhousedao/reactor-browser`.
|
|
57
|
+
|
|
58
|
+
The generic plugin's UI moved behind the plugin, which a project's routes follow by hand:
|
|
59
|
+
|
|
60
|
+
- `AppLayout`, `ConnectSidebar`, `SidebarDriveItems`, `SidebarNavItems` and `OpenDocument` import from `@powerhousedao/connect/generic`, not `/layout`.
|
|
61
|
+
- `@powerhousedao/connect/route-views` exports only `ConnectRoot`; `Home` (and its parts), `DriveLayout`, `NodeView`, `DrivePending` and `SettingsPage` import from `/generic`.
|
|
62
|
+
- `generic()`, `genericActive`, `IfPlugin` and `useIsPluginActive` are gone; a plugin's `ui()` provides its views.
|
|
63
|
+
- 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>" })`.
|
|
64
|
+
|