@ibgib/space-gib 0.0.33 → 0.0.34

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

@@ -0,0 +1,272 @@
+/**
+ * @module client/ui/router/space-gib-router-helpers
+ *
+ * Route parsing and formatting helpers for the Space-Gib Client Router.
+ * Pure isomorphic functions with zero DOM dependency.
+ */
+
+import {
+    SpaceGibRouteInfo, SpaceGibTenant,
+} from './space-gib-router-types.mjs';
+
+/**
+ * Safely decodes a URI component, returning the raw string if decoding fails.
+ */
+function safeDecode(str: string): string {
+    try {
+        return decodeURIComponent(str);
+    } catch {
+        return str;
+    }
+}
+
+/**
+ * Parses a browser pathname into a structured SpaceGibRouteInfo.
+ *
+ * Supports:
+ * - Polycosmos: / or /polycosmos or /@:siteUsername or /keystone/:keystoneTjp
+ * - Cosmos: /:cosmos or /@:siteUsername/:cosmos or /keystone/:keystoneTjp/:cosmos
+ * - Code Galaxy: /:cosmos/code/:galaxyId[/:branch[/*filePath]]
+ * - Notes Galaxy: /:cosmos/notes/:galaxyId[/:topicTjp]
+ * - Raw Addr (Snapshot): /:cosmos/:spaceId/addr/:ibGibAddr
+ * - Raw Tjp (Living Tip): /:cosmos/:spaceId/tjp/:tjpAddr
+ * - Admin Review: /admin/review[/:tjpGib]
+ */
+export function parseSpaceGibRoute(pathname: string): SpaceGibRouteInfo {
+    let p = (pathname || '').trim();
+
+    let queryObj: Record<string, string> | undefined;
+    const qIdx = p.indexOf('?');
+    if (qIdx !== -1) {
+        const qStr = p.substring(qIdx + 1);
+        p = p.substring(0, qIdx);
+        const searchParams = new URLSearchParams(qStr);
+        const q: Record<string, string> = {};
+        searchParams.forEach((val, key) => {
+            q[key] = val;
+        });
+        if (Object.keys(q).length > 0) {
+            queryObj = q;
+        }
+    }
+    const hIdx = p.indexOf('#');
+    if (hIdx !== -1) { p = p.substring(0, hIdx); }
+
+    if (!p || p === '/') {
+        return { kind: 'polycosmos' };
+    }
+
+    // Special Route: /admin/review
+    if (p === '/admin/review') {
+        return { kind: 'admin-review' };
+    }
+    if (p.startsWith('/admin/review/')) {
+        const tjpGib = safeDecode(p.slice('/admin/review/'.length)).trim();
+        return { kind: 'admin-review', ...(tjpGib ? { tjpGib } : {}) };
+    }
+
+    const rawSegments = p.split('/').filter(s => s.length > 0);
+    if (rawSegments.length === 0) {
+        return { kind: 'polycosmos' };
+    }
+
+    // Extract tenant prefix if present (@username or /keystone/tjp)
+    let tenant: SpaceGibTenant | undefined;
+    let segIdx = 0;
+
+    if (rawSegments[0].startsWith('@')) {
+        const username = safeDecode(rawSegments[0].slice(1)).trim();
+        if (username) {
+            tenant = { type: 'username', siteUsername: username };
+            segIdx = 1;
+        }
+    } else if (rawSegments[0] === 'keystone' && rawSegments.length > 1) {
+        const keystoneTjp = safeDecode(rawSegments[1]).trim();
+        if (keystoneTjp) {
+            tenant = { type: 'keystone', keystoneTjp };
+            segIdx = 2;
+        }
+    }
+
+    const remaining = rawSegments.slice(segIdx);
+
+    // If only tenant specifier was given (e.g. /@bill or /keystone/tjp123)
+    if (remaining.length === 0) {
+        return { kind: 'polycosmos', ...(tenant ? { tenant } : {}) };
+    }
+
+    if (remaining.length === 1 && remaining[0] === 'polycosmos') {
+        return { kind: 'polycosmos', ...(tenant ? { tenant } : {}) };
+    }
+
+    const cosmos = safeDecode(remaining[0]).trim();
+
+    if (remaining.length === 1) {
+        return { kind: 'cosmos', ...(tenant ? { tenant } : {}), cosmos };
+    }
+
+    const second = safeDecode(remaining[1]).trim();
+
+    // Code Galaxy: /:cosmos/code/:galaxyId[/:branch[/*filePath]]
+    if (second === 'code') {
+        const galaxyId = remaining[2] ? safeDecode(remaining[2]).trim() : '';
+        if (!galaxyId) {
+            return { kind: 'cosmos', ...(tenant ? { tenant } : {}), cosmos };
+        }
+        const branch = remaining[3] ? safeDecode(remaining[3]).trim() : undefined;
+        const filePath = remaining.length > 4 ? remaining.slice(4).map(safeDecode).join('/') : undefined;
+        return {
+            kind: 'code-galaxy',
+            ...(tenant ? { tenant } : {}),
+            cosmos,
+            galaxyId,
+            ...(branch ? { branch } : {}),
+            ...(filePath ? { filePath } : {}),
+        };
+    }
+
+    // Notes Galaxy: /:cosmos/notes/:galaxyId[/tjp/:tjp1/:tjp2...] or [/addr/:addr1/:addr2...] or [/:topicTjp]
+    if (second === 'notes') {
+        const galaxyId = remaining[2] ? safeDecode(remaining[2]).trim() : '';
+        if (!galaxyId) {
+            return { kind: 'cosmos', ...(tenant ? { tenant } : {}), cosmos };
+        }
+
+        let trailMode: 'tjp' | 'addr' | undefined;
+        let trail: string[] | undefined;
+        let topicTjp: string | undefined;
+
+        if (remaining.length > 3) {
+            const modeCandidate = safeDecode(remaining[3]).trim();
+            if (modeCandidate === 'tjp' || modeCandidate === 'addr') {
+                trailMode = modeCandidate;
+                const trailSegments = remaining.slice(4).map(s => safeDecode(s).trim()).filter(s => s.length > 0);
+                if (trailSegments.length > 0) {
+                    trail = trailSegments;
+                    topicTjp = trailSegments[0];
+                }
+            } else {
+                // Backward compatibility / shorthand: /notes/:galaxyId/:topicTjp
+                topicTjp = modeCandidate;
+                trailMode = 'tjp';
+                trail = [modeCandidate];
+            }
+        }
+
+        return {
+            kind: 'notes-galaxy',
+            ...(tenant ? { tenant } : {}),
+            cosmos,
+            galaxyId,
+            ...(trailMode ? { trailMode } : {}),
+            ...(trail ? { trail } : {}),
+            ...(topicTjp ? { topicTjp } : {}),
+            ...(queryObj ? { query: queryObj } : {}),
+        };
+    }
+
+    // Mechanism 1: Space-Qualified Raw Addrs
+    // /:cosmos/:spaceId/addr/:ibGibAddr
+    // /:cosmos/:spaceId/tjp/:tjpAddr
+    if (remaining.length >= 4) {
+        const third = safeDecode(remaining[2]).trim();
+        const spaceId = second;
+        if (third === 'addr') {
+            const ibGibAddr = safeDecode(remaining.slice(3).join('/')).trim();
+            return {
+                kind: 'raw-addr',
+                ...(tenant ? { tenant } : {}),
+                cosmos,
+                spaceId,
+                ibGibAddr,
+            };
+        }
+        if (third === 'tjp') {
+            const tjpAddr = safeDecode(remaining.slice(3).join('/')).trim();
+            return {
+                kind: 'raw-tjp',
+                ...(tenant ? { tenant } : {}),
+                cosmos,
+                spaceId,
+                tjpAddr,
+            };
+        }
+    }
+
+    // Fallback: Cosmos route
+    return { kind: 'cosmos', ...(tenant ? { tenant } : {}), cosmos };
+}
+
+/**
+ * Formats a SpaceGibRouteInfo into a canonical URL pathname.
+ */
+export function formatSpaceGibRoute(route: SpaceGibRouteInfo): string {
+    if (route.kind === 'admin-review') {
+        return `/admin/review${route.tjpGib ? `/${encodeURIComponent(route.tjpGib)}` : ''}`;
+    }
+
+    let prefix = '';
+    if (route.tenant) {
+        if (route.tenant.type === 'username') {
+            prefix = `/@${encodeURIComponent(route.tenant.siteUsername)}`;
+        } else if (route.tenant.type === 'keystone') {
+            prefix = `/keystone/${encodeURIComponent(route.tenant.keystoneTjp)}`;
+        }
+    }
+
+    switch (route.kind) {
+        case 'polycosmos':
+            return prefix ? `${prefix}/polycosmos` : '/';
+
+        case 'cosmos':
+            return `${prefix}/${encodeURIComponent(route.cosmos)}`;
+
+        case 'code-galaxy': {
+            let res = `${prefix}/${encodeURIComponent(route.cosmos)}/code/${encodeURIComponent(route.galaxyId)}`;
+            if (route.branch) {
+                res += `/${encodeURIComponent(route.branch)}`;
+                if (route.filePath) {
+                    res += `/${route.filePath.split('/').map(encodeURIComponent).join('/')}`;
+                }
+            }
+            return res;
+        }
+
+        case 'notes-galaxy': {
+            let res = `${prefix}/${encodeURIComponent(route.cosmos)}/notes/${encodeURIComponent(route.galaxyId)}`;
+            if (route.trail && route.trail.length > 0) {
+                const mode = route.trailMode || 'tjp';
+                res += `/${mode}/${route.trail.map(encodeURIComponent).join('/')}`;
+            } else if (route.topicTjp) {
+                res += `/${encodeURIComponent(route.topicTjp)}`;
+            }
+            if (route.query && Object.keys(route.query).length > 0) {
+                const sp = new URLSearchParams();
+                for (const [k, v] of Object.entries(route.query)) {
+                    if (v !== undefined) { sp.set(k, v); }
+                }
+                const qs = sp.toString();
+                if (qs) { res += `?${qs}`; }
+            }
+            return res;
+        }
+
+        case 'raw-addr':
+            return `${prefix}/${encodeURIComponent(route.cosmos)}/${encodeURIComponent(route.spaceId)}/addr/${encodeURIComponent(route.ibGibAddr)}`;
+
+        case 'raw-tjp':
+            return `${prefix}/${encodeURIComponent(route.cosmos)}/${encodeURIComponent(route.spaceId)}/tjp/${encodeURIComponent(route.tjpAddr)}`;
+
+        default:
+            return '/';
+    }
+}
+
+/**
+ * Compares two routes for equivalence by comparing their canonical formatted paths.
+ */
+export function isSameRoute(a?: SpaceGibRouteInfo, b?: SpaceGibRouteInfo): boolean {
+    if (!a && !b) { return true; }
+    if (!a || !b) { return false; }
+    return formatSpaceGibRoute(a) === formatSpaceGibRoute(b);
+}

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

@@ -0,0 +1,353 @@
+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,
+    CodeGalaxyRouteInfo,
+    NotesGalaxyRouteInfo,
+    RawAddrRouteInfo,
+    RawTjpRouteInfo,
+} from './space-gib-router-types.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, 'Code Galaxy Routes', async () => {
+        await ifWe(sir, 'parses /my-cosmos/code/code-1 with galaxyId', async () => {
+            const route = parseSpaceGibRoute('/my-cosmos/code/code-1');
+            iReckon(sir, route.kind).willEqual('code-galaxy');
+            const cg = route as CodeGalaxyRouteInfo;
+            iReckon(sir, cg.cosmos).willEqual('my-cosmos');
+            iReckon(sir, cg.galaxyId).willEqual('code-1');
+            iReckon(sir, cg.branch).willEqual(undefined);
+            iReckon(sir, cg.filePath).willEqual(undefined);
+        });
+
+        await ifWe(sir, 'parses /my-cosmos/code/code-1/main with branch', async () => {
+            const route = parseSpaceGibRoute('/my-cosmos/code/code-1/main');
+            iReckon(sir, route.kind).willEqual('code-galaxy');
+            const cg = route as CodeGalaxyRouteInfo;
+            iReckon(sir, cg.cosmos).willEqual('my-cosmos');
+            iReckon(sir, cg.galaxyId).willEqual('code-1');
+            iReckon(sir, cg.branch).willEqual('main');
+            iReckon(sir, cg.filePath).willEqual(undefined);
+        });
+
+        await ifWe(sir, 'parses /my-cosmos/code/code-1/main/src/index.ts with branch and deep filePath', async () => {
+            const route = parseSpaceGibRoute('/my-cosmos/code/code-1/main/src/index.ts');
+            iReckon(sir, route.kind).willEqual('code-galaxy');
+            const cg = route as CodeGalaxyRouteInfo;
+            iReckon(sir, cg.cosmos).willEqual('my-cosmos');
+            iReckon(sir, cg.galaxyId).willEqual('code-1');
+            iReckon(sir, cg.branch).willEqual('main');
+            iReckon(sir, cg.filePath).willEqual('src/index.ts');
+        });
+
+        await ifWe(sir, 'parses /@bill/my-cosmos/code/code-1/feat-x/src/deep/nested/file.mts with tenant and deep path', async () => {
+            const route = parseSpaceGibRoute('/@bill/my-cosmos/code/code-1/feat-x/src/deep/nested/file.mts');
+            iReckon(sir, route.kind).willEqual('code-galaxy');
+            const cg = route as CodeGalaxyRouteInfo;
+            const tenant = cg.tenant;
+            iReckon(sir, tenant?.type).willEqual('username');
+            if (tenant && tenant.type === 'username') {
+                iReckon(sir, tenant.siteUsername).willEqual('bill');
+            }
+            iReckon(sir, cg.cosmos).willEqual('my-cosmos');
+            iReckon(sir, cg.galaxyId).willEqual('code-1');
+            iReckon(sir, cg.branch).willEqual('feat-x');
+            iReckon(sir, cg.filePath).willEqual('src/deep/nested/file.mts');
+        });
+    });
+
+    await respecfully(sir, 'Notes Galaxy Routes', async () => {
+        await ifWe(sir, 'parses /my-cosmos/notes/notes-1 with galaxyId', async () => {
+            const route = parseSpaceGibRoute('/my-cosmos/notes/notes-1');
+            iReckon(sir, route.kind).willEqual('notes-galaxy');
+            const ng = route as NotesGalaxyRouteInfo;
+            iReckon(sir, ng.cosmos).willEqual('my-cosmos');
+            iReckon(sir, ng.galaxyId).willEqual('notes-1');
+            iReckon(sir, ng.topicTjp).willEqual(undefined);
+        });
+
+        await ifWe(sir, 'parses /my-cosmos/notes/notes-1/topic_abc with topicTjp', async () => {
+            const route = parseSpaceGibRoute('/my-cosmos/notes/notes-1/topic_abc');
+            iReckon(sir, route.kind).willEqual('notes-galaxy');
+            const ng = route as NotesGalaxyRouteInfo;
+            iReckon(sir, ng.cosmos).willEqual('my-cosmos');
+            iReckon(sir, ng.galaxyId).willEqual('notes-1');
+            iReckon(sir, ng.topicTjp).willEqual('topic_abc');
+        });
+
+        await ifWe(sir, 'parses /@bill/my-cosmos/notes/notes-1/topic_abc with tenant and topicTjp', async () => {
+            const route = parseSpaceGibRoute('/@bill/my-cosmos/notes/notes-1/topic_abc');
+            iReckon(sir, route.kind).willEqual('notes-galaxy');
+            const ng = route as NotesGalaxyRouteInfo;
+            const tenant = ng.tenant;
+            iReckon(sir, tenant?.type).willEqual('username');
+            if (tenant && tenant.type === 'username') {
+                iReckon(sir, tenant.siteUsername).willEqual('bill');
+            }
+            iReckon(sir, ng.cosmos).willEqual('my-cosmos');
+            iReckon(sir, ng.galaxyId).willEqual('notes-1');
+            iReckon(sir, ng.topicTjp).willEqual('topic_abc');
+            iReckon(sir, ng.trailMode).willEqual('tjp');
+            iReckon(sir, ng.trail?.length).willEqual(1);
+            iReckon(sir, ng.trail?.[0]).willEqual('topic_abc');
+        });
+
+        await ifWe(sir, 'parses /@bill/my-cosmos/notes/notes-1/tjp/topic_1/reply_2/reply_3 as n-depth tjp trail', async () => {
+            const route = parseSpaceGibRoute('/@bill/my-cosmos/notes/notes-1/tjp/topic_1/reply_2/reply_3');
+            iReckon(sir, route.kind).willEqual('notes-galaxy');
+            const ng = route as NotesGalaxyRouteInfo;
+            iReckon(sir, ng.cosmos).willEqual('my-cosmos');
+            iReckon(sir, ng.galaxyId).willEqual('notes-1');
+            iReckon(sir, ng.trailMode).willEqual('tjp');
+            iReckon(sir, ng.trail?.length).willEqual(3);
+            iReckon(sir, ng.trail?.[0]).willEqual('topic_1');
+            iReckon(sir, ng.trail?.[1]).willEqual('reply_2');
+            iReckon(sir, ng.trail?.[2]).willEqual('reply_3');
+            iReckon(sir, ng.topicTjp).willEqual('topic_1');
+        });
+
+        await ifWe(sir, 'parses /my-cosmos/notes/notes-1/addr/hash1/hash2 as n-depth reified addr trail', async () => {
+            const route = parseSpaceGibRoute('/my-cosmos/notes/notes-1/addr/hash1/hash2');
+            iReckon(sir, route.kind).willEqual('notes-galaxy');
+            const ng = route as NotesGalaxyRouteInfo;
+            iReckon(sir, ng.cosmos).willEqual('my-cosmos');
+            iReckon(sir, ng.galaxyId).willEqual('notes-1');
+            iReckon(sir, ng.trailMode).willEqual('addr');
+            iReckon(sir, ng.trail?.length).willEqual(2);
+            iReckon(sir, ng.trail?.[0]).willEqual('hash1');
+            iReckon(sir, ng.trail?.[1]).willEqual('hash2');
+        });
+
+        await ifWe(sir, 'parses query params for right-panel inspector and lenses', async () => {
+            const route = parseSpaceGibRoute('/@bill/my-cosmos/notes/notes-1/tjp/topic_1?inspect=src%2Findex.ts%23L10&lens=issues');
+            iReckon(sir, route.kind).willEqual('notes-galaxy');
+            const ng = route as NotesGalaxyRouteInfo;
+            iReckon(sir, ng.query?.inspect).willEqual('src/index.ts#L10');
+            iReckon(sir, ng.query?.lens).willEqual('issues');
+        });
+    });
+
+    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: 'code-galaxy', cosmos: 'my-cosmos', galaxyId: 'code-1' },
+            { kind: 'code-galaxy', cosmos: 'my-cosmos', galaxyId: 'code-1', branch: 'main' },
+            { kind: 'code-galaxy', cosmos: 'my-cosmos', galaxyId: 'code-1', branch: 'main', filePath: 'src/core/index.ts' },
+            { kind: 'code-galaxy', tenant: { type: 'username', siteUsername: 'bill' }, cosmos: 'my-cosmos', galaxyId: 'code-1', branch: 'dev', filePath: 'lib/utils.ts' },
+            { kind: 'notes-galaxy', cosmos: 'my-cosmos', galaxyId: 'notes-1' },
+            { kind: 'notes-galaxy', cosmos: 'my-cosmos', galaxyId: 'notes-1', topicTjp: 'topic_welcome', trailMode: 'tjp', trail: ['topic_welcome'] },
+            { kind: 'notes-galaxy', tenant: { type: 'username', siteUsername: 'bill' }, cosmos: 'my-cosmos', galaxyId: 'notes-1', topicTjp: 'topic_welcome', trailMode: 'tjp', trail: ['topic_welcome'] },
+            { kind: 'notes-galaxy', cosmos: 'my-cosmos', galaxyId: 'notes-1', topicTjp: 't1', trailMode: 'tjp', trail: ['t1', 't2', 't3'] },
+            { kind: 'notes-galaxy', cosmos: 'my-cosmos', galaxyId: 'notes-1', trailMode: 'addr', trail: ['a1', 'a2'] },
+            { kind: 'notes-galaxy', cosmos: 'my-cosmos', galaxyId: 'notes-1', 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/code-1/');
+            iReckon(sir, route.kind).willEqual('code-galaxy');
+            iReckon(sir, (route as CodeGalaxyRouteInfo).galaxyId).willEqual('code-1');
+        });
+
+        await ifWe(sir, 'strips query parameters', async () => {
+            const route = parseSpaceGibRoute('/my-cosmos/code/code-1?branch=main&debug=true');
+            iReckon(sir, route.kind).willEqual('code-galaxy');
+            iReckon(sir, (route as CodeGalaxyRouteInfo).galaxyId).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///code-1///');
+            iReckon(sir, route.kind).willEqual('code-galaxy');
+            iReckon(sir, (route as CodeGalaxyRouteInfo).galaxyId).willEqual('code-1');
+        });
+    });
+});