Add session-scoped state and improve Springboard dev/runtime behavior

[mickmister]

Summary

This PR improves Springboard development/runtime behavior and adds a new tab-scoped state primitive for browser-based apps.

What changed

• Added createLocalSessionState to the module state API for state backed by sessionStorage.
• Added BrowserSessionKVStoreService and wired optional session storage through browser, offline browser, Tauri browser, and generated web entrypoints.
• Updated core dependency/module dependency types and engine initialization to create a session shared-state service when session storage is available.
• Improved Vite dev HMR handling so user-code changes re-run the Springboard engine after module reloads.
• Made user-code HMR detection path-based and cross-platform, excluding generated/build/dependency directories.
• Updated the node server template to respect process.env.PORT at runtime, falling back to the configured build-time port.
• Documented the new LocalSessionState state type and when to use it.
• Added kv-2.db to .gitignore to avoid committing local KV database files.

Why

The branch supports building richer Springboard apps that need browser-tab-specific UI/navigation state without persisting it across sessions or syncing it across devices. This is useful for temporary app state such as wizard progress, tab-local drafts, or per-window navigation state.

It also improves the local development loop: when app source changes, the Springboard engine is re-initialized after HMR so newly registered/updated modules run correctly. Runtime PORT support makes generated node builds easier to deploy in environments where the port is assigned dynamically.

Implementation details

• CoreDependencies.storage.session is optional so non-browser or older integrations can continue without providing session storage.
• Springboard.initialize() creates a SharedStateService for session storage only when storage.session exists, then exposes it through ModuleDependencies.services.sessionSharedStateService.
• StatesAPI.createLocalSessionState() uses the session shared-state service when available and falls back to user-agent/local storage when session storage is unavailable.
• Browser entrypoints instantiate BrowserSessionKVStoreService(sessionStorage) and pass it into startAndRenderBrowserApp.
• The Vite dev plugin identifies user code by checking paths under the configured project root while excluding node_modules, .springboard, and dist, then schedules nodeEntryModule.start() after reload.

[claude]

Claude finished @mickmister's task —— View job

---

Code Review Analysis

Reviewing the VK wrapper app pull request for code quality, best practices, and potential issues.

Todo List:

• Read and analyze changed files
• Review code quality and best practices
• Check for potential bugs or issues
• Evaluate performance considerations
• Assess security concerns
• Review test coverage
• Provide constructive feedback

---

Review Summary

This PR implements a new session storage-based state management API (createLocalSessionState) in the Springboard framework. The implementation is generally well-structured but has several areas for improvement.

🟢 Positive Aspects

1. Clear separation of concerns - New BrowserSessionKVStoreService is properly isolated
2. Consistent API design - Follows existing pattern for other storage types
3. Good documentation - Comprehensive markdown documentation with examples
4. Proper integration - Correctly wired through all necessary entrypoints
5. Graceful fallbacks - Falls back to UserAgentStateSupervisor when session storage unavailable

⚠️ Issues & Recommendations

Code Quality

1. Error Handling in JSON Operations (browser_session_kvstore_service.ts:16)

try {
    entriesAsRecord[key] = JSON.parse(value);
} catch (e) {
    // eslint-disable-line no-empty
}

Issue: Silent failures make debugging difficult
Fix: Log parsing errors or handle them explicitly

try {
    entriesAsRecord[key] = JSON.parse(value);
} catch (e) {
    console.warn(`Failed to parse sessionStorage value for key "${key}":`, e);
    // Optionally include the raw value
}

2. Inconsistent Environment Variable Usage

• web-entry.template.ts:13-14 uses import.meta.env.VITE_*
• online_entrypoint.ts:14-15 uses process.env.*

Fix: Standardize on import.meta.env for client-side code

3. Type Safety Issue (module_types.ts:8)

registerClassModulee: <T extends object>(cb: ModuleCallback<T>) => void;

Issue: Typo in property name - extra "e"
Fix: Remove the extra "e" or clarify if intentional

Performance Considerations

4. HMR Performance (dev.ts:247-251)

const isUserCode = isNodePlatformActive &&
    file.startsWith(options.root) &&
    !file.includes(path.sep + 'node_modules' + path.sep) &&
    !file.includes(path.sep + '.springboard' + path.sep) &&
    !file.includes(path.sep + 'dist' + path.sep);

Issue: Multiple string operations on every file change
Fix: Pre-compile exclusion patterns or use path-based checks

5. Memory Management
Session storage cleanup isn't explicitly handled - consider implementing size limits or TTL

Security Considerations

6. JSON Parsing Vulnerabilities
JSON.parse() without validation could be exploited with malformed data
Fix: Consider using a safer JSON parser or add validation

7. Session Storage Exposure
No mechanism to prevent storing sensitive data in session storage
Fix: Add warnings in docs or type constraints

Missing Test Coverage

Issue: No tests found for the new BrowserSessionKVStoreService
Fix: Add unit tests covering:

• Basic get/set operations
• JSON parsing edge cases
• getAll() functionality
• Error scenarios

Documentation Improvements

8. State Management Docs (springboard-state-management.md)
Good examples but could benefit from:

• Browser compatibility notes for sessionStorage
• Performance characteristics comparison
• Migration guide between state types

🔧 Suggested Actions

1. High Priority:

   • Fix the error handling in JSON operations
   • Add tests for BrowserSessionKVStoreService
   • Fix the typo in module_types.ts

2. Medium Priority:

   • Standardize environment variable usage
   • Optimize HMR file checking
   • Add session storage size/cleanup considerations

3. Low Priority:

   • Consider JSON parsing security improvements
   • Enhance documentation with browser compatibility notes

📊 Overall Assessment

Code Quality: 7/10 - Well-structured but needs error handling improvements
Security: 6/10 - Basic security practices followed, minor JSON parsing concerns
Performance: 7/10 - Generally efficient, HMR could be optimized
Test Coverage: 4/10 - Missing tests for new functionality

The implementation correctly follows Springboard's patterns and provides useful functionality. With the suggested improvements, this would be a solid addition to the framework.

---

[cloudflare-workers-and-pages]

Deploying jamtools-docs-new with    Cloudflare Pages

Latest commit:	7b8f423
Status:	✅  Deploy successful!
Preview URL:	https://358bd25d.jamtools-docs-new.pages.dev
Branch Preview URL:	https://vk-6c2d-vk-wrapper-app.jamtools-docs-new.pages.dev

View logs