@fluid-app/fluid-cli-theme-dev 0.1.58 → 0.1.60

package/README.md

@@ -63,6 +63,39 @@ replace one path and delete the other.
 | `--navigate`               | off         | Open browser navigator after start        |
 | `--root <path>`            | `.`         | Theme root directory                      |
 
+### Member page preview
+
+With `fluid theme dev` running, open `http://127.0.0.1:9292/_members` and
+choose a page under its member site. Draft pages are included. The URL keeps the
+site selection, for example:
+
+```text
+http://127.0.0.1:9292/_members/pages/media?members_site_id=123
+```
+
+After `/_members`, the path matches the account host's production path. The
+legacy `/accounts` prefix returned by member metadata is removed. Storefront
+pages keep their normal unprefixed URLs.
+
+Optional `member_type_id`, `country_id`, and `language_id` query parameters select
+the sample audience and locale. Without a member type, the preview allows
+unrestricted authoring; selecting a type applies that site's access rules. Each
+tab retains its own context through navigation, history, refresh, and live reload.
+This does not sign in as a real member or expose private member collections.
+Forms and authentication links cannot perform live member actions in preview.
+
+The selected theme must be accessible with your CLI login. Rendering requires a
+server with member-preview contract version 1. Set `FLUID_API_BASE` to use a local
+or staging Rails API; member assets use that environment. Credentials remain in
+the CLI process. The local server only accepts its configured host or loopback
+hosts and rejects cross-origin requests.
+
+Successful watched uploads refresh the page list before reloading. Failed uploads
+retain the last known routes, and a removed page returns an explicit error.
+`--live-reload off` disables automatic reload. System screens report unsupported
+until the separate sample-runtime integration ships. The navigation command
+integration is a separate follow-up; use `/_members` for this version.
+
 ### `fluid theme push`
 
 Upload local theme files to a remote theme:
@@ -166,3 +199,79 @@ For contributors working in `fluid-mono`:
 pnpm --filter @fluid-app/fluid-cli-theme-dev build
 node packages/cli/core/dist/bin/fluid.mjs theme --help
 ```
+
+### Choose a member preview page
+
+Run `fluid theme navigate` while the dev server is running, or start it with
+`fluid theme dev --navigate`, to use the same route picker. Member pages are
+grouped by site and include drafts. Storefront choices remain available.
+
+Use `--host` and `--port` for a custom local address. `theme navigate --theme <id>`
+must match the running server’s theme. The picker reads routes after acknowledged
+syncs and rechecks a member page before opening it. System screens appear only
+when the running preview runtime advertises support; unavailable screens are
+listed in the terminal. Cancelling the picker leaves the dev server running.
+
+### System-screen sample previews
+
+Member navigation also lists **profile, messaging, contacts, my-site, orders, and subscriptions** when
+both the Rails catalogue and the packaged CLI runtime support them. The CLI
+ships its own sample-only account-screen bundle; no CDN update or member login
+is needed. A missing bundle produces an explicit unavailable response instead
+of loading a live screen.
+
+Screen links use production paths under `/_members`, for example
+`/_members/profile/orders?members_site_id=42`. Detail navigation, refresh and
+browser back preserve the selected site and audience. Theme layouts, attribute
+settings and `--fluid-account-*` CSS overrides apply to these screens.
+
+Data is synthetic. Writes and sign-out are rejected; payment entry is disabled.
+These previews do not verify private member data or real member permissions.
+Screens outside the packaged catalogue remain unavailable. From source, run
+`pnpm --filter @fluid-app/fluid-cli-theme-dev build` before starting the CLI;
+this also builds and copies the shared sample runtime into the CLI package.
+
+### Using member preview in Mist
+
+Start the theme's local preview in Mist, open the **Pages** sidebar, then choose
+**Member pages**. Expand the group to see each site's custom pages (including
+drafts) and supported sample screens directly in the sidebar. The list comes
+from the running CLI's development theme, which can have a different ID from
+the source theme. Clicking a page keeps its site in `members_site_id`. You can
+also paste a `/_members/...?...` path into Mist's local preview address bar.
+
+The Prod tab and its URL editor remain available. The `/_members` prefix is
+local-only; use the actual member-site URL when viewing production. Real member
+authentication and private Liquid collections are outside the CLI sample-preview
+contract.
+
+### Troubleshooting member preview
+
+- **401/403:** renew `fluid login` and check permission to view the selected
+  company's theme. Browser member login cannot replace the CLI credential.
+- **404 after editing the manifest:** the page or site may have been removed.
+  Open `/_members` again after the upload succeeds.
+- **501 for a system screen:** the installed CLI does not include a compatible
+  sample runtime for that screen. Update the CLI; unsupported screens are not
+  silently opened on the live member site.
+- **502 / incompatible render response:** deploy the Rails member-preview
+  contract and use a CLI version that supports that contract.
+- **Source build:** build the theme CLI from the monorepo root. Its build needs
+  the shared account-screen source and creates the browser runtime in
+  `dist/dist-cli-preview`; a published package already contains these files.
+- **Local Rails:** set `FLUID_API_BASE` to your local API origin in the process
+  that starts the CLI. The default is `https://api.fluid.app`.
+
+Use a development theme for preview tests. `theme dev` creates an isolated
+copy by default; `--theme` explicitly targets an existing theme and syncs files
+to it. No preview command publishes the theme. The browser receives no member session, and sample data cannot verify live
+access rules.
+
+The package acceptance check is `pnpm --filter @fluid-app/fluid-cli-theme-dev run test:package`
+after building. It starts the compiled theme plugin through Commander with a disposable local
+API server, verifies draft selection, screen assets and detail URLs, then checks
+authorization expiry, unknown sites, unsupported screens and write rejection.
+Set `FLUID_THEME_PACKAGE_DIR` to an unpacked npm package to run the same check on
+the distribution artifact. It does not contact production.
+
+The fixture runner does not exercise core CLI plugin discovery or npm package exports. An installed `fluid theme dev` smoke test remains a release check.