@ibgib/space-gib 0.0.33 → 0.0.35

package/src/client/ui/router/space-gib-router-helpers.respec.mts

@@ -0,0 +1,529 @@
+import {
+    respecfully, iReckon, ifWe, ifWeMight // don't remove unused ifWe or ifWeMight
+} from '@ibgib/helper-gib/dist/respec-gib/respec-gib.mjs';
+const sir = `[${import.meta.url}]`;
+
+import {
+    parseSpaceGibRoute,
+    formatSpaceGibRoute,
+    isSameRoute,
+} from './space-gib-router-helpers.mjs';
+import {
+    SpaceGibRouteInfo,
+    PolycosmosRouteInfo,
+    CosmosRouteInfo,
+    GalaxyRouteInfo,
+    RawAddrRouteInfo,
+    RawTjpRouteInfo,
+} from './space-gib-router-types.mjs';
+import { CosmosIbGib_V1 } from '@ibgib/core-gib/dist/cosmology/cosmos/cosmos-types.mjs';
+import { IbGibRouterServiceBase, IbGibCosmosRouterServiceBase } from '@ibgib/web-gib/dist/ui/router/index.mjs';
+import { getSpaceGibRouterSvc, SpaceGibRouterService } from './space-gib-router-service.mjs';
+
+await respecfully(sir, 'SpaceGibRouterHelpers specs', async () => {
+
+    await respecfully(sir, 'Polycosmos Routes', async () => {
+        await ifWe(sir, 'parses root / as polycosmos', async () => {
+            const route = parseSpaceGibRoute('/');
+            iReckon(sir, route.kind).willEqual('polycosmos');
+            iReckon(sir, (route as PolycosmosRouteInfo).tenant).willEqual(undefined);
+        });
+
+        await ifWe(sir, 'parses empty path as polycosmos', async () => {
+            const route = parseSpaceGibRoute('');
+            iReckon(sir, route.kind).willEqual('polycosmos');
+        });
+
+        await ifWe(sir, 'parses /polycosmos as polycosmos', async () => {
+            const route = parseSpaceGibRoute('/polycosmos');
+            iReckon(sir, route.kind).willEqual('polycosmos');
+        });
+
+        await ifWe(sir, 'parses /@bill as polycosmos with username tenant', async () => {
+            const route = parseSpaceGibRoute('/@bill');
+            iReckon(sir, route.kind).willEqual('polycosmos');
+            const tenant = (route as PolycosmosRouteInfo).tenant;
+            iReckon(sir, tenant?.type).willEqual('username');
+            if (tenant && tenant.type === 'username') {
+                iReckon(sir, tenant.siteUsername).willEqual('bill');
+            }
+        });
+
+        await ifWe(sir, 'parses /@bill/polycosmos as polycosmos with username tenant', async () => {
+            const route = parseSpaceGibRoute('/@bill/polycosmos');
+            iReckon(sir, route.kind).willEqual('polycosmos');
+            const tenant = (route as PolycosmosRouteInfo).tenant;
+            iReckon(sir, tenant?.type).willEqual('username');
+            if (tenant && tenant.type === 'username') {
+                iReckon(sir, tenant.siteUsername).willEqual('bill');
+            }
+        });
+
+        await ifWe(sir, 'parses /keystone/tjp123 as polycosmos with keystone tenant', async () => {
+            const route = parseSpaceGibRoute('/keystone/tjp123');
+            iReckon(sir, route.kind).willEqual('polycosmos');
+            const tenant = (route as PolycosmosRouteInfo).tenant;
+            iReckon(sir, tenant?.type).willEqual('keystone');
+            if (tenant && tenant.type === 'keystone') {
+                iReckon(sir, tenant.keystoneTjp).willEqual('tjp123');
+            }
+        });
+
+        await ifWe(sir, 'parses /keystone/tjp123/polycosmos as polycosmos with keystone tenant', async () => {
+            const route = parseSpaceGibRoute('/keystone/tjp123/polycosmos');
+            iReckon(sir, route.kind).willEqual('polycosmos');
+            const tenant = (route as PolycosmosRouteInfo).tenant;
+            iReckon(sir, tenant?.type).willEqual('keystone');
+            if (tenant && tenant.type === 'keystone') {
+                iReckon(sir, tenant.keystoneTjp).willEqual('tjp123');
+            }
+        });
+    });
+
+    await respecfully(sir, 'Cosmos Routes', async () => {
+        await ifWe(sir, 'parses /my-cosmos as cosmos', async () => {
+            const route = parseSpaceGibRoute('/my-cosmos');
+            iReckon(sir, route.kind).willEqual('cosmos');
+            iReckon(sir, (route as CosmosRouteInfo).cosmos).willEqual('my-cosmos');
+            iReckon(sir, (route as CosmosRouteInfo).tenant).willEqual(undefined);
+        });
+
+        await ifWe(sir, 'parses /@bill/my-cosmos as cosmos with username tenant', async () => {
+            const route = parseSpaceGibRoute('/@bill/my-cosmos');
+            iReckon(sir, route.kind).willEqual('cosmos');
+            iReckon(sir, (route as CosmosRouteInfo).cosmos).willEqual('my-cosmos');
+            const tenant = (route as CosmosRouteInfo).tenant;
+            iReckon(sir, tenant?.type).willEqual('username');
+            if (tenant && tenant.type === 'username') {
+                iReckon(sir, tenant.siteUsername).willEqual('bill');
+            }
+        });
+
+        await ifWe(sir, 'parses /keystone/tjp123/my-cosmos as cosmos with keystone tenant', async () => {
+            const route = parseSpaceGibRoute('/keystone/tjp123/my-cosmos');
+            iReckon(sir, route.kind).willEqual('cosmos');
+            iReckon(sir, (route as CosmosRouteInfo).cosmos).willEqual('my-cosmos');
+            const tenant = (route as CosmosRouteInfo).tenant;
+            iReckon(sir, tenant?.type).willEqual('keystone');
+            if (tenant && tenant.type === 'keystone') {
+                iReckon(sir, tenant.keystoneTjp).willEqual('tjp123');
+            }
+        });
+    });
+
+    await respecfully(sir, 'Universal Galaxy Routes (Branching / Code Archetype)', async () => {
+        await ifWe(sir, 'parses /my-cosmos/code-1 with galaxy', async () => {
+            const route = parseSpaceGibRoute('/my-cosmos/code-1');
+            iReckon(sir, route.kind).willEqual('galaxy');
+            const g = route as GalaxyRouteInfo;
+            iReckon(sir, g.cosmos).willEqual('my-cosmos');
+            iReckon(sir, g.galaxy).willEqual('code-1');
+            iReckon(sir, g.topology).willEqual('branching');
+            iReckon(sir, g.branch).willEqual(undefined);
+            iReckon(sir, g.filePath).willEqual(undefined);
+        });
+
+        await ifWe(sir, 'parses /my-cosmos/code-1/main with branch', async () => {
+            const route = parseSpaceGibRoute('/my-cosmos/code-1/main');
+            iReckon(sir, route.kind).willEqual('galaxy');
+            const g = route as GalaxyRouteInfo;
+            iReckon(sir, g.cosmos).willEqual('my-cosmos');
+            iReckon(sir, g.galaxy).willEqual('code-1');
+            iReckon(sir, g.topology).willEqual('branching');
+            iReckon(sir, g.branch).willEqual('main');
+            iReckon(sir, g.filePath).willEqual(undefined);
+        });
+
+        await ifWe(sir, 'parses /my-cosmos/code-1/main/src/index.ts with branch and deep filePath', async () => {
+            const route = parseSpaceGibRoute('/my-cosmos/code-1/main/src/index.ts');
+            iReckon(sir, route.kind).willEqual('galaxy');
+            const g = route as GalaxyRouteInfo;
+            iReckon(sir, g.cosmos).willEqual('my-cosmos');
+            iReckon(sir, g.galaxy).willEqual('code-1');
+            iReckon(sir, g.topology).willEqual('branching');
+            iReckon(sir, g.branch).willEqual('main');
+            iReckon(sir, g.filePath).willEqual('src/index.ts');
+        });
+
+        await ifWe(sir, 'parses /@bill/my-cosmos/code-1/feat-x/src/deep/nested/file.mts with tenant and deep path', async () => {
+            const route = parseSpaceGibRoute('/@bill/my-cosmos/code-1/feat-x/src/deep/nested/file.mts');
+            iReckon(sir, route.kind).willEqual('galaxy');
+            const g = route as GalaxyRouteInfo;
+            const tenant = g.tenant;
+            iReckon(sir, tenant?.type).willEqual('username');
+            if (tenant && tenant.type === 'username') {
+                iReckon(sir, tenant.siteUsername).willEqual('bill');
+            }
+            iReckon(sir, g.cosmos).willEqual('my-cosmos');
+            iReckon(sir, g.galaxy).willEqual('code-1');
+            iReckon(sir, g.topology).willEqual('branching');
+            iReckon(sir, g.branch).willEqual('feat-x');
+            iReckon(sir, g.filePath).willEqual('src/deep/nested/file.mts');
+        });
+    });
+
+    await respecfully(sir, 'Universal Galaxy Routes (Linear / Notes Archetype)', async () => {
+        await ifWe(sir, 'parses /my-cosmos/notes-1 with galaxy', async () => {
+            const route = parseSpaceGibRoute('/my-cosmos/notes-1');
+            iReckon(sir, route.kind).willEqual('galaxy');
+            const g = route as GalaxyRouteInfo;
+            iReckon(sir, g.cosmos).willEqual('my-cosmos');
+            iReckon(sir, g.galaxy).willEqual('notes-1');
+            iReckon(sir, g.topology).willEqual('linear');
+            iReckon(sir, g.topicTjp).willEqual(undefined);
+        });
+
+        await ifWe(sir, 'parses /my-cosmos/notes-1/topic_abc with topicTjp shorthand', async () => {
+            const route = parseSpaceGibRoute('/my-cosmos/notes-1/topic_abc');
+            iReckon(sir, route.kind).willEqual('galaxy');
+            const g = route as GalaxyRouteInfo;
+            iReckon(sir, g.cosmos).willEqual('my-cosmos');
+            iReckon(sir, g.galaxy).willEqual('notes-1');
+            iReckon(sir, g.topology).willEqual('linear');
+            iReckon(sir, g.topicTjp).willEqual('topic_abc');
+        });
+
+        await ifWe(sir, 'parses /@bill/my-cosmos/notes-1/topic_abc with tenant and topicTjp', async () => {
+            const route = parseSpaceGibRoute('/@bill/my-cosmos/notes-1/topic_abc');
+            iReckon(sir, route.kind).willEqual('galaxy');
+            const g = route as GalaxyRouteInfo;
+            const tenant = g.tenant;
+            iReckon(sir, tenant?.type).willEqual('username');
+            if (tenant && tenant.type === 'username') {
+                iReckon(sir, tenant.siteUsername).willEqual('bill');
+            }
+            iReckon(sir, g.cosmos).willEqual('my-cosmos');
+            iReckon(sir, g.galaxy).willEqual('notes-1');
+            iReckon(sir, g.topology).willEqual('linear');
+            iReckon(sir, g.topicTjp).willEqual('topic_abc');
+            iReckon(sir, g.trailMode).willEqual('tjp');
+            iReckon(sir, g.trail?.length).willEqual(1);
+            iReckon(sir, g.trail?.[0]).willEqual('topic_abc');
+        });
+
+        await ifWe(sir, 'parses /@bill/my-cosmos/notes-1/tjp/topic_1/reply_2/reply_3 as n-depth tjp trail', async () => {
+            const route = parseSpaceGibRoute('/@bill/my-cosmos/notes-1/tjp/topic_1/reply_2/reply_3');
+            iReckon(sir, route.kind).willEqual('galaxy');
+            const g = route as GalaxyRouteInfo;
+            iReckon(sir, g.cosmos).willEqual('my-cosmos');
+            iReckon(sir, g.galaxy).willEqual('notes-1');
+            iReckon(sir, g.topology).willEqual('linear');
+            iReckon(sir, g.trailMode).willEqual('tjp');
+            iReckon(sir, g.trail?.length).willEqual(3);
+            iReckon(sir, g.trail?.[0]).willEqual('topic_1');
+            iReckon(sir, g.trail?.[1]).willEqual('reply_2');
+            iReckon(sir, g.trail?.[2]).willEqual('reply_3');
+            iReckon(sir, g.topicTjp).willEqual('reply_3');
+        });
+
+        await ifWe(sir, 'parses /my-cosmos/notes-1/addr/hash1/hash2 as n-depth reified addr trail', async () => {
+            const route = parseSpaceGibRoute('/my-cosmos/notes-1/addr/hash1/hash2');
+            iReckon(sir, route.kind).willEqual('galaxy');
+            const g = route as GalaxyRouteInfo;
+            iReckon(sir, g.cosmos).willEqual('my-cosmos');
+            iReckon(sir, g.galaxy).willEqual('notes-1');
+            iReckon(sir, g.topology).willEqual('linear');
+            iReckon(sir, g.trailMode).willEqual('addr');
+            iReckon(sir, g.trail?.length).willEqual(2);
+            iReckon(sir, g.trail?.[0]).willEqual('hash1');
+            iReckon(sir, g.trail?.[1]).willEqual('hash2');
+        });
+
+        await ifWe(sir, 'parses query params for right-panel inspector and lenses', async () => {
+            const route = parseSpaceGibRoute('/@bill/my-cosmos/notes-1/tjp/topic_1?inspect=src%2Findex.ts%23L10&lens=issues');
+            iReckon(sir, route.kind).willEqual('galaxy');
+            const g = route as GalaxyRouteInfo;
+            iReckon(sir, g.query?.inspect).willEqual('src/index.ts#L10');
+            iReckon(sir, g.query?.lens).willEqual('issues');
+        });
+    });
+
+    await respecfully(sir, 'Fail-Fast Legacy Route Rejection', async () => {
+        await ifWe(sir, 'rejects obsolete /code/ intermediate segment', async () => {
+            let threw = false;
+            let errorMsg = '';
+            try {
+                parseSpaceGibRoute('/my-cosmos/code/code-1');
+            } catch (e: any) {
+                threw = true;
+                errorMsg = e.message;
+            }
+            iReckon(sir, threw).willEqual(true);
+            iReckon(sir, errorMsg.includes('Legacy route rejected')).willEqual(true);
+            iReckon(sir, errorMsg.includes('FAIL FAST')).willEqual(true);
+        });
+
+        await ifWe(sir, 'rejects obsolete /notes/ intermediate segment', async () => {
+            let threw = false;
+            let errorMsg = '';
+            try {
+                parseSpaceGibRoute('/my-cosmos/notes/notes-1');
+            } catch (e: any) {
+                threw = true;
+                errorMsg = e.message;
+            }
+            iReckon(sir, threw).willEqual(true);
+            iReckon(sir, errorMsg.includes('Legacy route rejected')).willEqual(true);
+            iReckon(sir, errorMsg.includes('FAIL FAST')).willEqual(true);
+        });
+
+        await ifWe(sir, 'rejects tenant-prefixed legacy /code/ route', async () => {
+            let threw = false;
+            let errorMsg = '';
+            try {
+                parseSpaceGibRoute('/@bill/my-cosmos/code/code-1/main');
+            } catch (e: any) {
+                threw = true;
+                errorMsg = e.message;
+            }
+            iReckon(sir, threw).willEqual(true);
+            iReckon(sir, errorMsg.includes('Legacy route rejected')).willEqual(true);
+        });
+    });
+
+    await respecfully(sir, 'Option B: Cosmos Manifest Policy Retrieval', async () => {
+        const mockCosmos: CosmosIbGib_V1 = {
+            ib: 'cosmos mock',
+            gib: 'gib_mock',
+            data: {
+                cosmosName: 'custom-cosmos',
+                uuid: 'u-1',
+                timestamp: '2026-09-18T00:00:00Z',
+                galaxies: {
+                    'custom-canvas': {
+                        galaxyName: 'custom-canvas',
+                        discriminator: 'canvas',
+                        policy: {
+                            role: 'intrinsic',
+                            topology: 'branching',
+                            storageMode: 'text',
+                        },
+                    },
+                    'custom-chat': {
+                        galaxyName: 'custom-chat',
+                        discriminator: 'chat',
+                        policy: {
+                            role: 'extrinsic',
+                            topology: 'linear',
+                            storageMode: 'text',
+                        },
+                    },
+                },
+            },
+            rel8ns: {},
+        };
+
+        await ifWe(sir, 'resolves custom branching galaxy from cosmos manifest', async () => {
+            const route = parseSpaceGibRoute('/custom-cosmos/custom-canvas/branchA/canvas.json', { cosmosManifest: mockCosmos });
+            iReckon(sir, route.kind).willEqual('galaxy');
+            const g = route as GalaxyRouteInfo;
+            iReckon(sir, g.galaxy).willEqual('custom-canvas');
+            iReckon(sir, g.topology).willEqual('branching');
+            iReckon(sir, g.discriminator).willEqual('canvas');
+            iReckon(sir, g.branch).willEqual('branchA');
+            iReckon(sir, g.filePath).willEqual('canvas.json');
+        });
+
+        await ifWe(sir, 'resolves custom linear galaxy from cosmos manifest', async () => {
+            const route = parseSpaceGibRoute('/custom-cosmos/custom-chat/tjp/topicA/msg1', { cosmosManifest: mockCosmos });
+            iReckon(sir, route.kind).willEqual('galaxy');
+            const g = route as GalaxyRouteInfo;
+            iReckon(sir, g.galaxy).willEqual('custom-chat');
+            iReckon(sir, g.topology).willEqual('linear');
+            iReckon(sir, g.discriminator).willEqual('chat');
+            iReckon(sir, g.trailMode).willEqual('tjp');
+            iReckon(sir, g.trail?.length).willEqual(2);
+            iReckon(sir, g.trail?.[0]).willEqual('topicA');
+            iReckon(sir, g.trail?.[1]).willEqual('msg1');
+        });
+    });
+
+    await respecfully(sir, 'Mechanism 1: Space-Qualified Raw Addrs', async () => {
+        await ifWe(sir, 'parses /:cosmos/:spaceId/addr/:ibGibAddr snapshot route', async () => {
+            const route = parseSpaceGibRoute('/my-cosmos/space-1/addr/comment%20hello^gib_1');
+            iReckon(sir, route.kind).willEqual('raw-addr');
+            const ra = route as RawAddrRouteInfo;
+            iReckon(sir, ra.cosmos).willEqual('my-cosmos');
+            iReckon(sir, ra.spaceId).willEqual('space-1');
+            iReckon(sir, ra.ibGibAddr).willEqual('comment hello^gib_1');
+            iReckon(sir, ra.tenant).willEqual(undefined);
+        });
+
+        await ifWe(sir, 'parses /@bill/:cosmos/:spaceId/addr/:ibGibAddr with tenant', async () => {
+            const route = parseSpaceGibRoute('/@bill/my-cosmos/space-1/addr/comment%20hello^gib_1');
+            iReckon(sir, route.kind).willEqual('raw-addr');
+            const ra = route as RawAddrRouteInfo;
+            const tenant = ra.tenant;
+            iReckon(sir, tenant?.type).willEqual('username');
+            if (tenant && tenant.type === 'username') {
+                iReckon(sir, tenant.siteUsername).willEqual('bill');
+            }
+            iReckon(sir, ra.cosmos).willEqual('my-cosmos');
+            iReckon(sir, ra.spaceId).willEqual('space-1');
+            iReckon(sir, ra.ibGibAddr).willEqual('comment hello^gib_1');
+        });
+
+        await ifWe(sir, 'parses /:cosmos/:spaceId/tjp/:tjpAddr living tip route', async () => {
+            const route = parseSpaceGibRoute('/my-cosmos/space-1/tjp/tjp_living_tip');
+            iReckon(sir, route.kind).willEqual('raw-tjp');
+            const rt = route as RawTjpRouteInfo;
+            iReckon(sir, rt.cosmos).willEqual('my-cosmos');
+            iReckon(sir, rt.spaceId).willEqual('space-1');
+            iReckon(sir, rt.tjpAddr).willEqual('tjp_living_tip');
+            iReckon(sir, rt.tenant).willEqual(undefined);
+        });
+
+        await ifWe(sir, 'parses /keystone/tjp123/:cosmos/:spaceId/tjp/:tjpAddr with keystone tenant', async () => {
+            const route = parseSpaceGibRoute('/keystone/tjp123/my-cosmos/space-1/tjp/tjp_living_tip');
+            iReckon(sir, route.kind).willEqual('raw-tjp');
+            const rt = route as RawTjpRouteInfo;
+            const tenant = rt.tenant;
+            iReckon(sir, tenant?.type).willEqual('keystone');
+            if (tenant && tenant.type === 'keystone') {
+                iReckon(sir, tenant.keystoneTjp).willEqual('tjp123');
+            }
+            iReckon(sir, rt.cosmos).willEqual('my-cosmos');
+            iReckon(sir, rt.spaceId).willEqual('space-1');
+            iReckon(sir, rt.tjpAddr).willEqual('tjp_living_tip');
+        });
+    });
+
+    await respecfully(sir, 'Admin Review Routes', async () => {
+        await ifWe(sir, 'parses /admin/review', async () => {
+            const route = parseSpaceGibRoute('/admin/review');
+            iReckon(sir, route.kind).willEqual('admin-review');
+        });
+
+        await ifWe(sir, 'parses /admin/review/:tjpGib', async () => {
+            const route = parseSpaceGibRoute('/admin/review/tjp_challenge_999');
+            iReckon(sir, route.kind).willEqual('admin-review');
+            if (route.kind === 'admin-review') {
+                iReckon(sir, route.tjpGib).willEqual('tjp_challenge_999');
+            }
+        });
+    });
+
+    await respecfully(sir, 'Formatting and Round-Trip Equivalence', async () => {
+        const testCases: SpaceGibRouteInfo[] = [
+            { kind: 'polycosmos' },
+            { kind: 'polycosmos', tenant: { type: 'username', siteUsername: 'bill' } },
+            { kind: 'polycosmos', tenant: { type: 'keystone', keystoneTjp: 'tjp_genesis' } },
+            { kind: 'cosmos', cosmos: 'cosmos-alpha' },
+            { kind: 'cosmos', tenant: { type: 'username', siteUsername: 'bill' }, cosmos: 'cosmos-alpha' },
+            { kind: 'galaxy', cosmos: 'my-cosmos', galaxy: 'code-1', topology: 'branching' },
+            { kind: 'galaxy', cosmos: 'my-cosmos', galaxy: 'code-1', topology: 'branching', branch: 'main' },
+            { kind: 'galaxy', cosmos: 'my-cosmos', galaxy: 'code-1', topology: 'branching', branch: 'main', filePath: 'src/core/index.ts' },
+            { kind: 'galaxy', tenant: { type: 'username', siteUsername: 'bill' }, cosmos: 'my-cosmos', galaxy: 'code-1', topology: 'branching', branch: 'dev', filePath: 'lib/utils.ts' },
+            { kind: 'galaxy', cosmos: 'my-cosmos', galaxy: 'notes-1', topology: 'linear' },
+            { kind: 'galaxy', cosmos: 'my-cosmos', galaxy: 'notes-1', topology: 'linear', topicTjp: 'topic_welcome', trailMode: 'tjp', trail: ['topic_welcome'] },
+            { kind: 'galaxy', tenant: { type: 'username', siteUsername: 'bill' }, cosmos: 'my-cosmos', galaxy: 'notes-1', topology: 'linear', topicTjp: 'topic_welcome', trailMode: 'tjp', trail: ['topic_welcome'] },
+            { kind: 'galaxy', cosmos: 'my-cosmos', galaxy: 'notes-1', topology: 'linear', topicTjp: 't3', trailMode: 'tjp', trail: ['t1', 't2', 't3'] },
+            { kind: 'galaxy', cosmos: 'my-cosmos', galaxy: 'notes-1', topology: 'linear', trailMode: 'addr', trail: ['a1', 'a2'] },
+            { kind: 'galaxy', cosmos: 'my-cosmos', galaxy: 'notes-1', topology: 'linear', topicTjp: 't1', trailMode: 'tjp', trail: ['t1'], query: { inspect: 'src/index.ts#L10', lens: 'issues' } },
+            { kind: 'raw-addr', cosmos: 'my-cosmos', spaceId: 'branch_space_main', ibGibAddr: 'comment hello world^gib_1' },
+            { kind: 'raw-addr', tenant: { type: 'username', siteUsername: 'bill' }, cosmos: 'my-cosmos', spaceId: 'branch_space_main', ibGibAddr: 'comment hello world^gib_1' },
+            { kind: 'raw-tjp', cosmos: 'my-cosmos', spaceId: 'branch_space_main', tjpAddr: 'tjp_dna_123' },
+            { kind: 'admin-review' },
+            { kind: 'admin-review', tjpGib: 'tjp_review_abc' },
+        ];
+
+        for (const originalRoute of testCases) {
+            await ifWe(sir, `round-trips ${originalRoute.kind} correctly`, async () => {
+                const formatted = formatSpaceGibRoute(originalRoute);
+                const parsed = parseSpaceGibRoute(formatted);
+                iReckon(sir, isSameRoute(originalRoute, parsed)).willEqual(true);
+            });
+        }
+    });
+
+    await respecfully(sir, 'Edge Cases & Robustness', async () => {
+        await ifWe(sir, 'handles trailing slashes', async () => {
+            const route = parseSpaceGibRoute('/my-cosmos/code-1/');
+            iReckon(sir, route.kind).willEqual('galaxy');
+            iReckon(sir, (route as GalaxyRouteInfo).galaxy).willEqual('code-1');
+        });
+
+        await ifWe(sir, 'strips query parameters', async () => {
+            const route = parseSpaceGibRoute('/my-cosmos/code-1?branch=main&debug=true');
+            iReckon(sir, route.kind).willEqual('galaxy');
+            iReckon(sir, (route as GalaxyRouteInfo).galaxy).willEqual('code-1');
+        });
+
+        await ifWe(sir, 'strips hash fragments', async () => {
+            const route = parseSpaceGibRoute('/my-cosmos#section2');
+            iReckon(sir, route.kind).willEqual('cosmos');
+            iReckon(sir, (route as CosmosRouteInfo).cosmos).willEqual('my-cosmos');
+        });
+
+        await ifWe(sir, 'handles multiple consecutive slashes gracefully', async () => {
+            const route = parseSpaceGibRoute('///my-cosmos///code-1///');
+            iReckon(sir, route.kind).willEqual('galaxy');
+            iReckon(sir, (route as GalaxyRouteInfo).galaxy).willEqual('code-1');
+        });
+    });
+
+    await respecfully(sir, 'SpaceGibRouterService Subclass Specs', async () => {
+        await ifWeMight(sir, 'provides singleton subclassing IbGibCosmosRouterServiceBase and IbGibRouterServiceBase', async () => {
+            const router = getSpaceGibRouterSvc();
+            iReckon(sir, router instanceof SpaceGibRouterService).isGonnaBe(true);
+            iReckon(sir, router instanceof IbGibRouterServiceBase).isGonnaBe(true);
+            iReckon(sir, router instanceof IbGibCosmosRouterServiceBase).isGonnaBe(true);
+        });
+
+        await ifWeMight(sir, 'parses, formats and navigates cleanly via cosmos base class', async () => {
+            const router = getSpaceGibRouterSvc();
+            const received: SpaceGibRouteInfo[] = [];
+            const unsubscribe = router.subscribe(async (r) => {
+                received.push(r);
+            });
+
+            await router.navigate({
+                kind: 'galaxy',
+                cosmos: 'test-cosmos',
+                galaxy: 'notes-1',
+                topology: 'linear',
+            });
+
+            iReckon(sir, router.getCurrentRoute()?.kind).willEqual('galaxy');
+            iReckon(sir, (router.getCurrentRoute() as GalaxyRouteInfo).galaxy).willEqual('notes-1');
+            iReckon(sir, received.length > 0).isGonnaBe(true);
+
+            unsubscribe();
+        });
+
+        await ifWeMight(sir, 'auto-loads galaxy policy from manifest registered on router', async () => {
+            const router = getSpaceGibRouterSvc();
+            const mockManifest: CosmosIbGib_V1 = {
+                ib: 'cosmos test-auto-cosmos',
+                data: {
+                    cosmosName: 'test-auto-cosmos',
+                    galaxies: {
+                        'auto-canvas': {
+                            galaxyName: 'auto-canvas',
+                            discriminator: 'canvas',
+                            policy: {
+                                topology: 'branching',
+                                role: 'intrinsic',
+                                storageMode: 'text',
+                            },
+                        },
+                    },
+                },
+                rel8ns: {},
+            };
+            router.setCosmosManifest('test-auto-cosmos', mockManifest);
+
+            const received: SpaceGibRouteInfo[] = [];
+            const unsubscribe = router.subscribe((r) => { received.push(r); });
+
+            await router.navigatePath('/test-auto-cosmos/auto-canvas/branchX/art.png');
+
+            const current = router.getCurrentRoute() as GalaxyRouteInfo;
+            iReckon(sir, current.kind).willEqual('galaxy');
+            iReckon(sir, current.topology).willEqual('branching');
+            iReckon(sir, current.discriminator).willEqual('canvas');
+
+            unsubscribe();
+        });
+    });
+});

package/src/client/ui/router/space-gib-router-service.mts

@@ -0,0 +1,63 @@
+/**
+ * @module client/ui/router/space-gib-router-service
+ *
+ * Singleton HTML5 History API Cosmos router service for space-gib.
+ * Extends the Tier 2 IbGibCosmosRouterServiceBase from @ibgib/web-gib.
+ */
+
+import { IbGibCosmosRouterServiceBase, safeDecode } from '@ibgib/web-gib/dist/ui/router/index.mjs';
+
+import {
+    SpaceGibRouteInfo,
+    RouterNavigateOptions,
+    SpaceGibRouteListener,
+    AdminReviewRouteInfo,
+} from './space-gib-router-types.mjs';
+
+export class SpaceGibRouterService extends IbGibCosmosRouterServiceBase<SpaceGibRouteInfo> {
+    protected override lc: string = `[SpaceGibRouterService]`;
+
+    protected override parseCustomRoute(pathname: string): SpaceGibRouteInfo | undefined {
+        let cleanPath = (pathname || '').trim();
+        const qIdx = cleanPath.indexOf('?');
+        if (qIdx !== -1) { cleanPath = cleanPath.substring(0, qIdx); }
+        const hIdx = cleanPath.indexOf('#');
+        if (hIdx !== -1) { cleanPath = cleanPath.substring(0, hIdx); }
+
+        if (cleanPath === '/admin/review') {
+            return { kind: 'admin-review' };
+        }
+        if (cleanPath.startsWith('/admin/review/')) {
+            const tjpGib = safeDecode(cleanPath.slice('/admin/review/'.length)).trim();
+            return { kind: 'admin-review', ...(tjpGib ? { tjpGib } : {}) };
+        }
+        return undefined;
+    }
+
+    protected override formatCustomRoute(route: SpaceGibRouteInfo): string | undefined {
+        if (route.kind === 'admin-review') {
+            return `/admin/review${route.tjpGib ? `/${encodeURIComponent(route.tjpGib)}` : ''}`;
+        }
+        return undefined;
+    }
+
+    protected override isSameCustomRoute(a?: SpaceGibRouteInfo, b?: SpaceGibRouteInfo): boolean | undefined {
+        if (a?.kind === 'admin-review' || b?.kind === 'admin-review') {
+            if (a?.kind !== b?.kind) { return false; }
+            return (a as AdminReviewRouteInfo).tjpGib === (b as AdminReviewRouteInfo).tjpGib;
+        }
+        return undefined;
+    }
+}
+
+let routerSingleton: SpaceGibRouterService | undefined;
+
+/**
+ * Returns the singleton SpaceGibRouterService instance.
+ */
+export function getSpaceGibRouterSvc(): SpaceGibRouterService {
+    if (!routerSingleton) {
+        routerSingleton = new SpaceGibRouterService();
+    }
+    return routerSingleton;
+}

package/src/client/ui/router/space-gib-router-types.mts

@@ -0,0 +1,49 @@
+/**
+ * @module client/ui/router/space-gib-router-types
+ *
+ * Types for the Space-Gib Client Router.
+ * Re-exports universal Cosmos & Galaxy route types from @ibgib/web-gib,
+ * and adds space-gib specific routes (e.g. AdminReviewRouteInfo).
+ */
+
+import {
+    CosmosRouteInfo as WebGibCosmosRouteInfo,
+    CosmosTenant,
+    PolycosmosRouteInfo,
+    CosmosOnlyRouteInfo,
+    CosmosGalaxyRouteInfo,
+    CosmosRawAddrRouteInfo,
+    CosmosRawTjpRouteInfo,
+    RouterNavigateOptions,
+    RouteListener,
+} from '@ibgib/web-gib/dist/ui/router/index.mjs';
+
+export {
+    RouterNavigateOptions,
+    RouteListener,
+    PolycosmosRouteInfo,
+    CosmosGalaxyRouteInfo,
+    CosmosRawAddrRouteInfo,
+    CosmosRawTjpRouteInfo,
+};
+
+export type SpaceGibTenant = CosmosTenant;
+export type CosmosRouteInfo = CosmosOnlyRouteInfo;
+export type GalaxyRouteInfo = CosmosGalaxyRouteInfo;
+export type RawAddrRouteInfo = CosmosRawAddrRouteInfo;
+export type RawTjpRouteInfo = CosmosRawTjpRouteInfo;
+
+export interface AdminReviewRouteInfo {
+    kind: 'admin-review';
+    tjpGib?: string;
+}
+
+export type SpaceGibRouteInfo =
+    | CosmosRouteInfo
+    | GalaxyRouteInfo
+    | PolycosmosRouteInfo
+    | RawAddrRouteInfo
+    | RawTjpRouteInfo
+    | AdminReviewRouteInfo;
+
+export type SpaceGibRouteListener = RouteListener<SpaceGibRouteInfo>;