Skip to content

docs(apps): say where preview app state lives and that it does not sync - #2647

Merged
Leela8256 merged 1 commit into
developfrom
fix/RR-2468-preview-appstate
Oct 15, 2026
Merged

Leela8256 merged 1 commit into
developfrom
fix/RR-2468-preview-appstate

Conversation

@Leela8256

@Leela8256 Leela8256 commented Oct 15, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

  • The App Builder preview and the published @me app keep separate saved state, which looks like data loss when switching between them (Design preview and the published @me app hold separate appState #2468). In the 6 October review the lead ruled the separation is by design and asked for the reporter's use case before any UI change, so this is documentation only: no badge, no tooltip, no code.
  • docs/agents/context/ROCKETRIDE_APPS.md (State & Persistence) and the App Builder guide now say where an app's prefs and appState are saved: in the signed-in user's file store on the connected development server, in .workspace/<appId>.workspace.json, keyed by app id only. The preview runs against the development server, so its state lives there; the published @me app lives on the deployment target. A different server or app id means a different file; the same server, user and app id means one file that both read, with no sync and the last save winning, so finish in one, close it, then reload the other before editing there. With Inherit Auth on the preview is signed in as the App Builder is; with it off, as whoever signs in inside it. App-written files are per server and user, with no app id or version in the path.
  • Every claim was checked against develop: packages/shell/src/hooks/useWorkspaceState.ts (path, app-id key, debounced whole-state write, one load per connect), packages/ai/src/ai/account/file_store.py and cmd_store.py (per-user tree), packages/shell/src/util/devMode.ts (the preview's session). Wording describes behaviour, not the server-side dev overlay, so it stays true when App Builder in the cloud: unified shell bus, devtool platform, local-first dev previews #2625 lands.

Type

docs

Testing

  • python3 scripts/validate-client-docs.py; git diff --check; anchors match the table of contents; line wrap matches both files.
  • Not a code change; no tests.

Checklist

  • Commit messages follow conventional commits
  • No secrets or credentials included
  • Wiki updated (if applicable)
  • Breaking changes documented (none)

Linked Issue

Refs #2468 (the visual indicator the issue also asks for waits for the reporter's use case, per the 6 October review)

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Documentation
    • Clarified how app state persists across previews and published versions, and how it is scoped by server, signed-in user, and app ID.
    • Explained that pages sharing a state file can overwrite one another’s saved state, and distinguished app state from files written through the shell connection.

The shell saves an app's `prefs` and `appState` in the signed-in user's
file store on the server the page is connected to, in a file named
after the app id (`.workspace/<appId>.workspace.json`). The App Builder
preview runs against the connected development server
(`ROCKETRIDE_URI`), so the state it saves lives in that server's file
store, while the published @me app lives on the deployment target: on
different servers, or under another app id, each copy has its own file.
When the deployment target is the development server and the user and
app id are the same, both read one file but nothing syncs: each page
keeps the copy it loaded and writes it back whole, so the last save
wins. Files the app writes itself through the shell connection are per
server and user, with no app id or version in the path. To a developer
this looks exactly like data loss (#2468), and nothing in the docs said
so.

The separation is by design, per the 6 October review decision; this is
a docs-only change: no UI, badge or tooltip.

- ROCKETRIDE_APPS.md: a paragraph under State & Persistence saying which
  server "on the server" means, how versions, app ids and the preview
  relate to the state file, which user the preview is signed in as
  (Inherit Auth), and how app-written files are scoped; a one-line
  pointer from the Preview bullet of the Design panes.
- Public App Builder guide: the same facts in the Design section.

Refs #2468

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@github-actions

Copy link
Copy Markdown
Contributor
🤖 Internal: Discord sync marker

Auto-managed by the Discord notification workflow. Stores the linked Discord message ID and forum thread ID. Do not edit or delete.

@coderabbitai

coderabbitai Bot commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
  • Configuration used: Repository: rocketride-org/rocketride-server/.coderabbit.yaml
  • Review profile: ASSERTIVE
  • Plan: Advanced
  • Run ID: ae56ba3f-0629-4de3-bef4-01531a90e71d
📥 Commits

Reviewing files that changed from the base of the PR and between 64693e8 and 4d76430.

📒 Files selected for processing: 2
  • docs/agents/context/ROCKETRIDE_APPS.md
  • docs/public/product/guides/apps/app-builder.md

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 9 remain after this review.

📝 Walkthrough

The app documentation now explains how preview state is stored and shared across servers, users, app IDs, and deployed versions. It also distinguishes preview state from files written through the shell connection.

Changes: App state persistence documentation

Layer / File(s) Summary
Document app state scope and persistence
docs/agents/context/ROCKETRIDE_APPS.md, docs/public/product/guides/apps/app-builder.md
The documentation describes preview state storage and sharing, including last-save-wins behavior when pages use the same file. It also explains preview authentication inheritance and distinguishes app state from shell-written files.

Priority: ⬇️ Low

Estimated code review effort: 1 (Trivial) | ~5 minutes

Change: Other

Merge Risk: ⚪ Minimal · up to 4d764

The documentation clarifies when preview and published apps share saved state and when they do not. No issue requiring a fix before merge is established.

Pre-merge checks: Passed 5
Passed Passed checks: 5 passed
Check name Status Explanation
Description Check Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check Passed The title clearly and concisely describes the documentation change about preview app state storage and synchronization.
Docstring Coverage Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 0…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@asclearuc asclearuc left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you @Leela8256 for writing this down.

The new State & Persistence text and the App Builder note explain the preview / @me split as "two files, not data loss", and I checked the claims against the code: the state file is keyed by app id only (appPath in useWorkspaceState.ts), each page writes its whole state back (debounced fsWriteJson), Inherit Auth defaults to on (DesignView.tsx), and a plain file path resolves to users/<client_id>/files (resolve_scope in file_store.py).

Approve

No inline comments.

@Leela8256
Leela8256 merged commit 74aeaf1 into develop Oct 15, 2026
@Leela8256
Leela8256 deleted the fix/RR-2468-preview-appstate branch October 15, 2026 22:22
Leela8256 added a commit that referenced this pull request Nov 7, 2026
… one allows (#3076)

* docs(vscode): explain the connection modes, their names and what each one allows

One mode has three names ("onprem" in settings, "Direct Connect" in the
dropdown, "Direct" in the status bar), the status bar names neither the
host nor what the mode allows, and the docs said little more (#2473).
This explains the current behavior in the docs. Every statement was
checked against develop.

- usage.md: a new Connection Modes section. One table of the five modes
  with every name the extension shows for each, what runs where, what
  each needs (Docker and Service need Install on their panel the first
  time), and what publishing and developer registration do there.
  Deploying, publishing and registering go to the development
  connection's server, and the extension checks only that it is live.
  An open-source server (Local, Docker, Service) publishes under the
  fixed developer id "rocketride" without review and refuses developer
  registration. A RocketRide Cloud server needs a registered developer
  id and reviews @public releases. The section says which features use
  the development connection (running, the DEPLOY page, the App
  Builder) and which use the deployment connection. Subsections cover
  the status bar texts and where to see the host, and what switching
  modes changes, including the Cloud subscription gate on Run, the app
  namespace and the palette.
- usage.md: "Deploying to Cloud" becomes "Deploying a Pipeline": the
  DEPLOY page publishes to the development connection's server, which
  is not always RocketRide Cloud.
- usage.md: the .env Auto-Sync section now matches the code. Every mode
  syncs, Cloud included, the deployment connection writes its own
  ROCKETRIDE_DEPLOY_* pair, a Cloud sign-out empties the key, and the
  rocketride CLI reads .env too. It said only self-hosted development
  connections synced and that nothing was ever cleared.
- installation.md: the Welcome steps list the five modes, say which
  mode takes a URL or key and that Docker and Service need Install
  first, name the Save & Connect button and link to the table; the
  hostUrl rows say only Direct Connect uses them.
- index.md: the connection manager bullet and the connectionMode row
  point to the table; both hostUrl rows say only Direct Connect uses
  them.

Re-verified against develop 7b687e4 after #2625 landed: the text now
names the Settings page's Connections and Environment Variables
sections and the sidebar menu, and no longer edits
deployment-webview.md, whose postMessage protocol #2625 removed.

Docs only, so no CHANGELOG entry, as for #2534, #2647 and #2613. #2625
kept the mode names: the status bar and the sidebar menu still read
"Connected (Direct)" and name no host. Naming the mode and host in the
UI is left for a code change.

Closes #2473

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs(vscode): Linux libraries, first-run status texts and .env precedence

Three gaps in the connection-modes text: the Local row said a user needs
nothing, but on Linux the engine needs libc++1, libc++abi1 and libgomp1,
which the extension checks at the first start and offers to install with
apt; the Welcome steps said the status bar reads Disconnected before the
Docker or Service install, but it reads Setup until the first save; and the
.env section did not say that the Python SDK and the rocketride CLI leave a
variable that is already in the process environment alone, so a pair
exported before a target switch keeps pointing at the old server until it
is unset or re-exported.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

* docs(vscode): name the Linux libraries per distribution

The Local row gave only the Debian and Ubuntu package names. It now names
the libraries, the apt packages the extension offers to install, and the
Fedora and RHEL packages (`libcxx`, `libcxxabi`, `libgomp`), the same names
the self-hosting and development pages use.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

---------

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
AviNormie pushed a commit to AviNormie/rocketride-server that referenced this pull request Nov 9, 2026
…nc (rocketride-org#2647)

The shell saves an app's `prefs` and `appState` in the signed-in user's
file store on the server the page is connected to, in a file named
after the app id (`.workspace/<appId>.workspace.json`). The App Builder
preview runs against the connected development server
(`ROCKETRIDE_URI`), so the state it saves lives in that server's file
store, while the published @me app lives on the deployment target: on
different servers, or under another app id, each copy has its own file.
When the deployment target is the development server and the user and
app id are the same, both read one file but nothing syncs: each page
keeps the copy it loaded and writes it back whole, so the last save
wins. Files the app writes itself through the shell connection are per
server and user, with no app id or version in the path. To a developer
this looks exactly like data loss (rocketride-org#2468), and nothing in the docs said
so.

The separation is by design, per the 6 October review decision; this is
a docs-only change: no UI, badge or tooltip.

- ROCKETRIDE_APPS.md: a paragraph under State & Persistence saying which
  server "on the server" means, how versions, app ids and the preview
  relate to the state file, which user the preview is signed in as
  (Inherit Auth), and how app-written files are scoped; a one-line
  pointer from the Preview bullet of the Design panes.
- Public App Builder guide: the same facts in the Design section.

Refs rocketride-org#2468

Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants