): ActionFn;
@@ -223,6 +337,7 @@ interface CoreDependencies {
storage: {
remote: KVStore;
userAgent: KVStore;
+ session?: KVStore;
};
rpc: {
remote: Rpc;
@@ -276,6 +391,14 @@ declare module 'springboard/module_registry/module_registry' {
}
}
\`\`\`
+
+## React Module Access
+
+\`\`\`typescript
+import {useModule} from 'springboard/engine/engine';
+
+const moduleApi = useModule('myModule');
+\`\`\`
`;
console.log(types);
diff --git a/packages/springboard/create-springboard-app/src/cli.ts b/packages/springboard/create-springboard-app/src/cli.ts
index 24b42aca..5bb18a83 100644
--- a/packages/springboard/create-springboard-app/src/cli.ts
+++ b/packages/springboard/create-springboard-app/src/cli.ts
@@ -103,33 +103,172 @@ program
writeFileSync(`${process.cwd()}/vite.config.ts`, viteString);
console.log('Created vite config vite.config.ts');
- const agentDocsContent = `# Springboard Development Guide
+ const agentDocsContent = `Keep the following info in mind *when working in the ./src directory only*
-This application is built with the **Springboard framework**.
+After making any changes, run \`npm run check-types\` to ensure types pass.
-## Getting Started
+This application is built with the **Springboard framework**. All code is assumed to be isomorphic by default. Optionally run \`npx sb docs context\` for more info.
-**Before writing any code, run:**
+Example module:
-\`\`\`bash
-npx sb docs context
+\`\`\`tsx
+import springboard from 'springboard';
+
+type ExampleSharedState = {
+ version: 1;
+ items: [] as Array<{id: string; name: string}>;
+}
+
+springboard.registerModule('ModuleName', {}, async (moduleAPI) => {
+ const sharedState = await moduleAPI.createStates({
+
+ exampleSharedState: {
+ version: 1; // Later we can do \`version: 1 | 2\` and perform data migrations as needed
+ items: [],
+ } as ExampleSharedState,
+ });
+
+ const myClientState = await moduleAPI.createUserAgentState('mySettings', {theme: null} as {theme: string | null});
+
+ const myServerActions = moduleAPI.createActions({
+ addItem: (args: {name: string}) => {
+ const newItem = {id: generateid(), name: args.name};
+
+ sharedState.exampleSharedState.setStateImmer(state => {
+ state.push(newItem);
+ });
+
+ // or
+ sharedState.exampleSharedState.setState(state => {
+ return [...state, newItem];
+ });
+
+ const someOtherModule = moduleAPI.getModule('SomeOptionalModule');
+ someOtherModule?.actions.doSomething(); // Optional chaining, since module was registered as optional in its own type declaration. Good for modules that only exist on certain platform builds.
+
+ return {data: newItem};
+ },
+ })
+
+ // Register UI routes
+ moduleAPI.registerRoute('/', {}, (navigate) => {
+ const liveState = sharedState.useState();
+
+ return (
+
+
+
+ );
+ });
+
+ // Return public API
+ return { sharedState, actions };
+});
+
+// Declare module return value for other files
+declare module 'springboard/module_registry/module_registry' {
+ interface AllModules {
+ ModuleName: {
+ sharedState: {
+ exampleSharedState: StateSupervisor;
+ };
+ actions: {
+ addItem: (args: {name: string}) => Promise;
+ };
+ };
+ }
+}
\`\`\`
-This outputs comprehensive framework information including available documentation
-sections, key concepts, and workflow guidance.
+To access these values in another file
+
+\`\`\`tsx
+import {useModule} from '../hooks/useModule';
+
+const MyComponent = () => {
+ const myModule = useModule('ModuleName');
+ const liveState = myModule.sharedState.exampleSharedState.useState();
+
+ const doThing = async () => {
+ await myModule.actions.addItem({name: 'example'});
+ };
+};
+\`\`\`
+
+If importing a node module in an action, you'll need to use conditional compilation. Springboard is written in a way so that actions *can* run on the client, but our application here is only deployed as a server-driven SPA, so all actions will run on the server in this app.
+
+\`\`\`tsx
+const myActions = moduleAPI.createActions({
+ myAction: async () => {
+ // @platform "node"
+ const fs = await import ('fs');
+ // ...
+ // @platform end
+ },
+});
+
+// Or import a server only module
+
+// @platform "node"
+import './modules/MyServerOnlyModule';
+// @platform end
+
+// More rarely, you may want to remove code from the server build that only runs on the frontend. It's necessary sometimes.
+
+// @platform "browser"
+window.addEventListener('load', () => {
+
+});
+// @platform end
+\`\`\`
+
+
+# GitNexus — Code Intelligence
+
+This project is indexed by GitNexus as **vibe-kanban-vscode-web** (940 symbols, 1601 relationships, 64 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
+
+> If any GitNexus tool warns the index is stale, run \`npx gitnexus analyze\` in terminal first.
+
+## Always Do
+
+- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run \`gitnexus_impact({target: "symbolName", direction: "upstream"})\` and report the blast radius (direct callers, affected processes, risk level) to the user.
+- **MUST run \`gitnexus_detect_changes()\` before committing** to verify your changes only affect expected symbols and execution flows.
+- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
+- When exploring unfamiliar code, use \`gitnexus_query({query: "concept"})\` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
+- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use \`gitnexus_context({name: "symbolName"})\`.
+
+## Never Do
+
+- NEVER edit a function, class, or method without first running \`gitnexus_impact\` on it.
+- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
+- NEVER rename symbols with find-and-replace — use \`gitnexus_rename\` which understands the call graph.
+- NEVER commit changes without running \`gitnexus_detect_changes()\` to check affected scope.
+
+## Resources
-## Recommended Workflow
+| Resource | Use for |
+|----------|---------|
+| \`gitnexus://repo/vibe-kanban-vscode-web/context\` | Codebase overview, check index freshness |
+| \`gitnexus://repo/vibe-kanban-vscode-web/clusters\` | All functional areas |
+| \`gitnexus://repo/vibe-kanban-vscode-web/processes\` | All execution flows |
+| \`gitnexus://repo/vibe-kanban-vscode-web/process/{name}\` | Step-by-step execution trace |
-1. **Run \`sb docs context\`** at the start of your session
-2. **Write code** using your knowledge + the context from step 1
-3. **Fetch specific docs** only when needed: \`sb docs get \`
-4. **View examples** for reference code: \`sb docs examples show \`
+## CLI
-## Other Useful Commands
+| Task | Read this skill file |
+|------|---------------------|
+| Understand architecture / "How does X work?" | \`.claude/skills/gitnexus/gitnexus-exploring/SKILL.md\` |
+| Blast radius / "What breaks if I change X?" | \`.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md\` |
+| Trace bugs / "Why is X failing?" | \`.claude/skills/gitnexus/gitnexus-debugging/SKILL.md\` |
+| Rename / extract / split / refactor | \`.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md\` |
+| Tools, resources, schema reference | \`.claude/skills/gitnexus/gitnexus-guide/SKILL.md\` |
+| Index, status, clean, wiki CLI commands | \`.claude/skills/gitnexus/gitnexus-cli/SKILL.md\` |
-- \`sb docs --help\` - See all available commands
-- \`sb docs types\` - Get TypeScript type definitions
-- \`sb docs examples list\` - See available example modules
+
`;
writeFileSync(`${process.cwd()}/CLAUDE.md`, agentDocsContent);
writeFileSync(`${process.cwd()}/AGENTS.md`, agentDocsContent);
diff --git a/packages/springboard/package.json b/packages/springboard/package.json
index 71a7907b..305ccc95 100644
--- a/packages/springboard/package.json
+++ b/packages/springboard/package.json
@@ -132,6 +132,10 @@
"types": "./dist/platforms/browser/services/browser_kvstore_service.d.ts",
"import": "./dist/platforms/browser/services/browser_kvstore_service.js"
},
+ "./platforms/browser/services/browser_session_kvstore_service": {
+ "types": "./dist/platforms/browser/services/browser_session_kvstore_service.d.ts",
+ "import": "./dist/platforms/browser/services/browser_session_kvstore_service.js"
+ },
"./platforms/cloudflare-workers/entrypoints/cloudflare_entrypoint": {
"types": "./dist/platforms/cloudflare-workers/entrypoints/cloudflare_entrypoint.d.ts",
"import": "./dist/platforms/cloudflare-workers/entrypoints/cloudflare_entrypoint.js"
diff --git a/packages/springboard/src/core/engine/register.ts b/packages/springboard/src/core/engine/register.ts
index 9c225f2a..6a85acae 100644
--- a/packages/springboard/src/core/engine/register.ts
+++ b/packages/springboard/src/core/engine/register.ts
@@ -33,22 +33,50 @@ export type RegisterModuleOptions = {
type CapturedRegisterModuleCall = [string, RegisterModuleOptions, ModuleCallback];
+const getRegisterModuleCalls = (): CapturedRegisterModuleCall[] => {
+ const store = registerModule as unknown as {
+ calls?: CapturedRegisterModuleCall[];
+ };
+ return store.calls ? [...store.calls] : [];
+};
+
+const setRegisterModuleCalls = (calls: CapturedRegisterModuleCall[]): void => {
+ const store = registerModule as unknown as {
+ calls?: CapturedRegisterModuleCall[];
+ };
+ store.calls = calls;
+};
+
const registerModule = (
moduleName: string,
options: ModuleOptions,
cb: ModuleCallback,
) => {
- const calls = (registerModule as unknown as {calls: CapturedRegisterModuleCall[]}).calls || [];
+ const calls = getRegisterModuleCalls();
calls.push([moduleName, options, cb]);
- (registerModule as unknown as {calls: CapturedRegisterModuleCall[]}).calls = calls;
+ setRegisterModuleCalls(calls);
};
type CapturedRegisterClassModuleCalls = ClassModuleCallback;
+const getRegisterClassModuleCalls = (): CapturedRegisterClassModuleCalls[] => {
+ const store = registerClassModule as unknown as {
+ calls?: CapturedRegisterClassModuleCalls[];
+ };
+ return store.calls ? [...store.calls] : [];
+};
+
+const setRegisterClassModuleCalls = (calls: CapturedRegisterClassModuleCalls[]): void => {
+ const store = registerClassModule as unknown as {
+ calls?: CapturedRegisterClassModuleCalls[];
+ };
+ store.calls = calls;
+};
+
const registerClassModule = (cb: ClassModuleCallback) => {
- const calls = (registerClassModule as unknown as {calls: CapturedRegisterClassModuleCalls[]}).calls || [];
+ const calls = getRegisterClassModuleCalls();
calls.push(cb);
- (registerClassModule as unknown as {calls: CapturedRegisterClassModuleCalls[]}).calls = calls;
+ setRegisterClassModuleCalls(calls);
};
let registeredSplashScreen: React.ComponentType | null = null;
@@ -61,6 +89,18 @@ export const getRegisteredSplashScreen = (): React.ComponentType | null => {
return registeredSplashScreen;
};
+export const clearRegisteredModules = (): void => {
+ setRegisterModuleCalls([]);
+};
+
+export const clearRegisteredClassModules = (): void => {
+ setRegisterClassModuleCalls([]);
+};
+
+export const clearRegisteredSplashScreen = (): void => {
+ registeredSplashScreen = null;
+};
+
export const springboard: SpringboardRegistry = {
registerModule,
registerClassModule,
diff --git a/packages/springboard/src/server/hono_app.ts b/packages/springboard/src/server/hono_app.ts
index ae15ed28..552ebe51 100644
--- a/packages/springboard/src/server/hono_app.ts
+++ b/packages/springboard/src/server/hono_app.ts
@@ -23,6 +23,7 @@ type InitServerAppArgs = {
remoteKV: KVStore;
userAgentKV: KVStore;
broadcastMessage: (message: string) => void;
+ enableStaticRoutes?: boolean;
};
type InjectResourcesArgs = {
@@ -40,6 +41,8 @@ export const initApp = (initArgs: InitServerAppArgs): InitAppReturnValue => {
app.use('*', cors());
+ const enableStaticRoutes = initArgs.enableStaticRoutes ?? true;
+
const remoteKV = initArgs.remoteKV;
const userAgentKV = initArgs.userAgentKV;
@@ -187,38 +190,40 @@ export const initApp = (initArgs: InitServerAppArgs): InitAppReturnValue => {
let serveStaticFileFn: ((c: Context, fileName: string, headers: Record) => Promise) | undefined;
let getEnvValueFn: ((name: string) => string | undefined) | undefined;
- app.use('/', async (c) => {
- if (!serveStaticFileFn) {
- return c.text('Server not fully initialized', 500);
- }
- const headers = {
- 'Cache-Control': 'no-store, no-cache, must-revalidate',
- 'Pragma': 'no-cache',
- 'Expires': '0',
- 'Content-Type': 'text/html'
- };
- return serveStaticFileFn(c, 'index.html', headers);
- });
-
- app.use('/assets/:file', async (c, next) => {
- if (!serveStaticFileFn || !getEnvValueFn) {
- return c.text('Server not fully initialized', 500);
- }
+ if (enableStaticRoutes) {
+ app.use('/', async (c) => {
+ if (!serveStaticFileFn) {
+ return c.text('Server not fully initialized', 500);
+ }
+ const headers = {
+ 'Cache-Control': 'no-store, no-cache, must-revalidate',
+ 'Pragma': 'no-cache',
+ 'Expires': '0',
+ 'Content-Type': 'text/html'
+ };
+ return serveStaticFileFn(c, 'index.html', headers);
+ });
+
+ app.use('/assets/:file', async (c, next) => {
+ if (!serveStaticFileFn || !getEnvValueFn) {
+ return c.text('Server not fully initialized', 500);
+ }
- const requestedFile = c.req.param('file');
+ const requestedFile = c.req.param('file');
- if (requestedFile.endsWith('.map') && getEnvValueFn('NODE_ENV') === 'production') {
- return c.text('Source map disabled', 404);
- }
+ if (requestedFile.endsWith('.map') && getEnvValueFn('NODE_ENV') === 'production') {
+ return c.text('Source map disabled', 404);
+ }
- const contentType = requestedFile.endsWith('.js') ? 'text/javascript' : 'text/css';
- const headers = {
- 'Content-Type': contentType,
- 'Cache-Control': 'public, max-age=31536000, immutable'
- };
+ const contentType = requestedFile.endsWith('.js') ? 'text/javascript' : 'text/css';
+ const headers = {
+ 'Content-Type': contentType,
+ 'Cache-Control': 'public, max-age=31536000, immutable'
+ };
- return serveStaticFileFn(c, `assets/${requestedFile}`, headers);
- });
+ return serveStaticFileFn(c, `assets/${requestedFile}`, headers);
+ });
+ }
// app.use('/dist/manifest.json', serveStatic({
// root: webappDistFolder,
@@ -287,19 +292,21 @@ export const initApp = (initArgs: InitServerAppArgs): InitAppReturnValue => {
// },
// }));
- app.use('*', async (c) => {
- if (!serveStaticFileFn) {
- return c.text('Server not fully initialized', 500);
- }
- const headers = {
- 'Cache-Control': 'no-store, no-cache, must-revalidate',
- 'Pragma': 'no-cache',
- 'Expires': '0',
- 'Content-Type': 'text/html'
- };
-
- return serveStaticFileFn(c, 'index.html', headers);
- });
+ if (enableStaticRoutes) {
+ app.use('*', async (c) => {
+ if (!serveStaticFileFn) {
+ return c.text('Server not fully initialized', 500);
+ }
+ const headers = {
+ 'Cache-Control': 'no-store, no-cache, must-revalidate',
+ 'Pragma': 'no-cache',
+ 'Expires': '0',
+ 'Content-Type': 'text/html'
+ };
+
+ return serveStaticFileFn(c, 'index.html', headers);
+ });
+ }
const injectResources = (args: InjectResourcesArgs) => {
if (storedEngine) {
diff --git a/packages/springboard/src/server/register.ts b/packages/springboard/src/server/register.ts
index 3bc17116..8025c87e 100644
--- a/packages/springboard/src/server/register.ts
+++ b/packages/springboard/src/server/register.ts
@@ -11,15 +11,37 @@ export type ServerModuleCallback = (server: ServerModuleAPI) => void;
type CapturedRegisterServerModuleCall = ServerModuleCallback;
+const getRegisterServerModuleCalls = (): CapturedRegisterServerModuleCall[] => {
+ const store = registerServerModule as unknown as {
+ calls?: CapturedRegisterServerModuleCall[];
+ };
+ return store.calls ? [...store.calls] : [];
+};
+
+const setRegisterServerModuleCalls = (calls: CapturedRegisterServerModuleCall[]): void => {
+ const store = registerServerModule as unknown as {
+ calls?: CapturedRegisterServerModuleCall[];
+ };
+ store.calls = calls;
+};
+
const registerServerModule = (
cb: ServerModuleCallback,
) => {
- const calls = (registerServerModule as unknown as {calls: CapturedRegisterServerModuleCall[]}).calls || [];
+ const calls = getRegisterServerModuleCalls();
calls.push(cb);
- (registerServerModule as unknown as {calls: CapturedRegisterServerModuleCall[]}).calls = calls;
+ setRegisterServerModuleCalls(calls);
};
export type ServerModuleRegistry = {
+ /**
+ * Register server routes and server-scoped hooks.
+ *
+ * Server modules may attach route handlers and RPC middleware, but should
+ * not replace global Hono fallback behavior such as `notFound()`.
+ * Development mode relies on the framework-owned fallback remaining intact
+ * so browser requests can fall through to Vite when no server route matches.
+ */
registerServerModule: (
cb: ServerModuleCallback,
) => void;
@@ -29,6 +51,15 @@ export const serverRegistry: ServerModuleRegistry = {
registerServerModule,
};
+export const clearRegisteredServerModules = (): void => {
+ setRegisterServerModuleCalls([]);
+};
+
+export const resetServerRegistry = (): void => {
+ clearRegisteredServerModules();
+ serverRegistry.registerServerModule = registerServerModule;
+};
+
export type RpcMiddleware = (c: Context) => Promise