@ibgib/space-gib 0.0.1

package/src/client/constants.mts

@@ -0,0 +1,76 @@
+import { tagTextToIb } from "@ibgib/core-gib/dist/common/other/ibgib-helper.mjs";
+import { ZERO_SPACE_ID } from "@ibgib/core-gib/dist/witness/space/space-constants.mjs";
+import { IbGibAmbientContextConfig } from "@ibgib/web-gib/dist/app-bootstrap/types.mjs";
+
+// ---------------------------------------------------------------------------
+// Logging / debug
+// ---------------------------------------------------------------------------
+
+export const GLOBAL_LOG_A_LOT = false;
+
+// ---------------------------------------------------------------------------
+// Storage — unique per app instance
+// ---------------------------------------------------------------------------
+
+export const SPACE_GIB_DB_NAME = 'space_gib_db';
+export const SPACE_GIB_STORE_NAME = 'space_gib_store';
+export const SPACE_GIB_API_KEY_NAME = 'space_gib_api_key';
+
+export const SPACE_GIB_INDEXEDDB_KEY_LOCAL_SPACE_NAME = 'local_space_name';
+/**
+ * Prefix for the automatically generated local space name on first visit.
+ * A random suffix is appended at runtime.
+ */
+export const SPACE_GIB_INDEXEDDB_LOCAL_SPACE_NAME_PREFIX = 'space_gib_';
+
+// ---------------------------------------------------------------------------
+// App identity discriminator
+// ---------------------------------------------------------------------------
+
+export const HTML_META_APP_ID_NAME = "ibgib-app-id";
+export const HTML_META_APP_ID_CONTENT = "0c45ac92e668410190b115512d5e2d51";
+
+// ---------------------------------------------------------------------------
+// Agent / AI (optional)
+// ---------------------------------------------------------------------------
+
+export const GEMINI_API_KEY_REGEXP = /^[a-zA-Z0-9\-_]{32,64}$/;
+export const CONFIG_OPTION_GEMINI_API_KEY_LOCATION_HELP = `Gemini API Key config option (⚙️ icon)`;
+
+// ---------------------------------------------------------------------------
+// Tags
+// ---------------------------------------------------------------------------
+
+export const TAG_AGENT_TEXT = "agent";
+export const TAG_AGENT_ICON = "body-outline";
+export const TAG_AGENT_DESCRIPTION =
+    "This tag tracks the active agents for the current local user space.";
+export const TAG_AGENT_IB = tagTextToIb(TAG_AGENT_TEXT);
+
+// ---------------------------------------------------------------------------
+// Colors
+// ---------------------------------------------------------------------------
+
+export const DEFAULT_IBGIB_COLOR = '#78f87e88';
+export const DEFAULT_IBGIB_TRANSLUCENT = '#78f87e10';
+export const DEFAULT_IBGIB_COLOR_CONTRAST = '#ffffff';
+export const DEFAULT_TJP_COLOR = '#78f87e88';
+export const DEFAULT_TJP_COLOR_TRANSLUCENT = '#78f87e10';
+export const DEFAULT_TJP_COLOR_CONTRAST = '#ffffff';
+
+// ---------------------------------------------------------------------------
+// Server API base URL (relative — same origin serves both API and SPA)
+// ---------------------------------------------------------------------------
+
+export const API_BASE_URL = '/api';
+
+// ---------------------------------------------------------------------------
+// Ambient context config
+// ---------------------------------------------------------------------------
+
+export const APP_CONFIG: IbGibAmbientContextConfig = {
+    dbName: SPACE_GIB_DB_NAME,
+    storeName: SPACE_GIB_STORE_NAME,
+    additionalStoreNames: [ZERO_SPACE_ID],
+    apiKeyName: SPACE_GIB_API_KEY_NAME,
+};

package/src/client/custom.d.ts

@@ -0,0 +1,11 @@
+// Tell TypeScript that importing a .html file will return a string.
+declare module '*.html' {
+  const value: string;
+  export default value;
+}
+
+// Tell TypeScript that importing a .css file will return a string.
+declare module '*.css' {
+  const value: string;
+  export default value;
+}

package/src/client/dev-tools.mts

@@ -0,0 +1,540 @@
+/**
+ * @module client/dev-tools
+ *
+ * Wires up the Dev Tools panel button handlers for manual testing during
+ * development. Import this from index.mts inside the DOMContentLoaded handler.
+ *
+ * ## intent
+ *
+ * Remove or gate this module once the real sync WebSocket endpoint is confirmed
+ * working end-to-end.
+ */
+
+import { extractErrorMsg, getTimestamp, getUUID, HashAlgorithm } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+import { Factory_V1 as factory } from '@ibgib/ts-gib/dist/V1/factory.mjs';
+import { ROOT } from '@ibgib/ts-gib/dist/V1/constants.mjs';
+import { getIbGibAddr, } from '@ibgib/ts-gib/dist/helper.mjs';
+import { IbGib_V1 } from '@ibgib/ts-gib/dist/V1/types.mjs';
+import { KeystoneService_V1 } from '@ibgib/core-gib/dist/keystone/keystone-service-v1.mjs';
+import { KeystoneChallengeType, KeystoneIbGib_V1, KeystoneReplenishStrategy } from '@ibgib/core-gib/dist/keystone/keystone-types.mjs';
+import { createManagePoolConfig } from '@ibgib/core-gib/dist/keystone/keystone-config-builder.mjs';
+import { getGlobalMetaspace_waitIfNeeded } from "@ibgib/web-gib/dist/helpers.mjs";
+
+import { GLOBAL_LOG_A_LOT } from './constants.mjs';
+import { SESSION_KEYSTONE_POLICY, getHandshakeChallenge } from "../common/keystone-policies.mjs";
+import { KeystoneStrategyFactory } from '@ibgib/core-gib/dist/keystone/strategy/keystone-strategy-factory.mjs';
+import { SpaceGibApiBridge } from './api/space-gib-api-bridge.mjs';
+import { KeystoneVerb } from '@ibgib/core-gib/dist/keystone/keystone-constants.mjs';
+
+const logalot = GLOBAL_LOG_A_LOT
+const lc = '[dev-tools]';
+
+interface DebugState {
+    domainI?: KeystoneIbGib_V1;
+    domainIMasterSecret?: string;
+    targetX?: IbGib_V1;
+    sessionS?: KeystoneIbGib_V1;
+    sessionSecret?: string;
+}
+
+export const debugState: DebugState = {};
+(window as any).ibgibDebugState = debugState;
+
+// ---------------------------------------------------------------------------
+// Dev panel log helper
+// ---------------------------------------------------------------------------
+
+export function devLog(msg: string): void {
+    const logEl = document.getElementById('dev-panel-log') as HTMLPreElement | null;
+    if (!logEl) { return; }
+    const timestamp = new Date().toISOString().slice(11, 23); // HH:MM:SS.mmm
+    logEl.textContent = `[${timestamp}] ${msg}\n` + logEl.textContent;
+}
+
+// ---------------------------------------------------------------------------
+// Test WebSocket button
+// ---------------------------------------------------------------------------
+
+let _ws: WebSocket | null = null;
+
+function initWsTestButton(): void {
+    const lc_fn = `${lc}[initWsTestButton]`;
+    const btn = document.getElementById('btn-test-ws') as HTMLButtonElement | null;
+    if (!btn) {
+        console.warn(`${lc_fn} btn-test-ws not found — skipping`);
+        return;
+    }
+
+    btn.addEventListener('click', () => {
+        try {
+            if (_ws && _ws.readyState === WebSocket.OPEN) {
+                // Already connected — send a test ping instead
+                _ws.send(JSON.stringify({ ping: 'hello from client', ts: Date.now() }));
+                devLog('→ sent ping on existing connection');
+                return;
+            }
+
+            // Build the WebSocket URL from the current origin (wss:// if https://)
+            const protocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
+            const wsUrl = `${protocol}//${location.host}/api/debug/ws-echo`;
+            devLog(`→ connecting to ${wsUrl}`);
+
+            _ws = new WebSocket(wsUrl);
+
+            _ws.addEventListener('open', () => {
+                devLog('✓ WebSocket connected');
+                btn.textContent = 'Send WS Ping';
+            });
+
+            _ws.addEventListener('message', (ev) => {
+                devLog(`← ${ev.data}`);
+            });
+
+            _ws.addEventListener('close', (ev) => {
+                devLog(`✗ WebSocket closed (code ${ev.code})`);
+                btn.textContent = 'Test WebSocket';
+                _ws = null;
+            });
+
+            _ws.addEventListener('error', (ev) => {
+                devLog(`✗ WebSocket error — check console`);
+                console.error(`${lc_fn} WebSocket error`, ev);
+            });
+
+        } catch (error) {
+            devLog(`✗ ${extractErrorMsg(error)}`);
+            console.error(`${lc_fn} ${extractErrorMsg(error)}`);
+        }
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Print Dev State button
+// ---------------------------------------------------------------------------
+
+function initPrintStateButton(): void {
+    const btn = document.getElementById('btn-print-dev-state') as HTMLButtonElement | null;
+    if (!btn) return;
+    btn.addEventListener('click', () => {
+        devLog(`Printing debug state to console...`);
+        console.dir(debugState);
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Create Domain Keystone (I) button
+// ---------------------------------------------------------------------------
+
+function initCreateDomainKeystoneButton(): void {
+    const lc_fn = `${lc}[initCreateDomainKeystoneButton]`;
+    const btn = document.getElementById('btn-create-domain-keystone') as HTMLButtonElement | null;
+    if (!btn) return;
+
+    btn.addEventListener('click', async () => {
+        try {
+            btn.disabled = true;
+            devLog('Generating dummy Domain Keystone (I)...');
+
+            const metaspace = await getGlobalMetaspace_waitIfNeeded();
+            const space = await metaspace.getLocalUserSpace({});
+            if (!space) { throw new Error("No default space found in metaspace."); }
+
+            const masterSecret = 'password'; // Hardcoded for debug as requested
+            const keystoneService = new KeystoneService_V1();
+
+            const domainI = await keystoneService.genesis({
+                masterSecret,
+                configs: [
+                    createManagePoolConfig({
+                        id: 'default',
+                        salt: await getUUID(),
+                        replenishStrategy: KeystoneReplenishStrategy.topUp,
+                    }),
+                ],
+                metaspace,
+                space,
+                frameDetails: { client: 'space-gib-web-dev', timestamp: getTimestamp() }
+            });
+
+            const iAddr = getIbGibAddr({ ibGib: domainI });
+            devLog(`✓ Local genesis complete: ${iAddr}`);
+
+            debugState.domainI = domainI;
+            debugState.domainIMasterSecret = masterSecret;
+
+            // Post to server
+            devLog(`Posting genesis keystone to server...`);
+            const apiBridge = new SpaceGibApiBridge();
+            const resSync = await apiBridge.postGenesisKeystone(domainI);
+            if (!resSync.success) {
+                devLog(`✗ Server rejected genesis keystone: ${resSync.message}`);
+                btn.disabled = false;
+                return;
+            }
+
+            devLog(`✓ Server accepted Domain Keystone (I)`);
+            btn.textContent = '✓ Domain Keystone Created';
+
+            // Enable next step
+            const nextBtn = document.getElementById('btn-create-test-ibgib') as HTMLButtonElement;
+            if (nextBtn) nextBtn.disabled = false;
+
+        } catch (error) {
+            devLog(`✗ ${extractErrorMsg(error)}`);
+            console.error(`${lc_fn} ${extractErrorMsg(error)}`);
+            btn.disabled = false;
+        }
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Create Test IbGib button
+// ---------------------------------------------------------------------------
+
+function initCreateTestIbGibButton(): void {
+    const lc_fn = `${lc}[initCreateTestIbGibButton]`;
+    const btn = document.getElementById('btn-create-test-ibgib') as HTMLButtonElement | null;
+    if (!btn) {
+        console.warn(`${lc_fn} btn-create-test-ibgib not found — skipping`);
+        return;
+    }
+
+    btn.addEventListener('click', async () => {
+        try {
+            devLog('Generating dummy X^Xtjp ibgib...');
+            const resX = await factory.firstGen({
+                parentIbGib: ROOT,
+                ib: 'test data',
+                data: { hello: 'world', random: Math.random() },
+                dna: true,
+                nCounter: true,
+                tjp: { uuid: true, timestamp: true }
+            });
+            const xIbGib = resX.newIbGib;
+            const xAddr = getIbGibAddr({ ibGib: xIbGib });
+
+            debugState.targetX = xIbGib;
+            devLog(`✓ Created X: ${xAddr}`);
+            btn.textContent = '✓ Test IbGib (X) Created';
+
+            // Enable next step
+            const nextBtn = document.getElementById('btn-create-session-keystone') as HTMLButtonElement;
+            if (nextBtn) nextBtn.disabled = false;
+        } catch (error) {
+            devLog(`✗ ${extractErrorMsg(error)}`);
+            console.error(`${lc_fn} ${extractErrorMsg(error)}`);
+        }
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Create Session Keystone (S^Stjp) button
+// ---------------------------------------------------------------------------
+
+function initCreateSessionKeystoneButton(): void {
+    const lc_fn = `${lc}[initCreateSessionKeystoneButton]`;
+    const btn = document.getElementById('btn-create-session-keystone') as HTMLButtonElement | null;
+    if (!btn) {
+        console.warn(`${lc_fn} btn-create-session-keystone not found — skipping`);
+        return;
+    }
+
+    btn.addEventListener('click', async () => {
+        try {
+            devLog('Generating Session Keystone (S^Stjp)...');
+
+            const domainI = debugState.domainI;
+            const targetX = debugState.targetX;
+
+            if (!domainI) { devLog('⚠ No domain keystone (I) found in state. Please Create Domain Keystone first.'); return; }
+            if (!targetX) { devLog('⚠ No target ibgib (X) found in state. Please Create Test IbGib first.'); return; }
+
+            const metaspace = await getGlobalMetaspace_waitIfNeeded();
+            const space = await metaspace.getLocalUserSpace({});
+            if (!space) { throw new Error("No default space found in metaspace."); }
+
+            const sessionSecret = 'ephemeral-' + Math.random().toString();
+            const keystoneService = new KeystoneService_V1();
+
+            console.warn(`${lc}[NAG] placeholder genesis keystone config right now (W: 69b108687cf8bec0f9a8e148bcca8d26)`);
+            const sIbGib = await keystoneService.genesis({
+                masterSecret: sessionSecret,
+                configs: [
+                    {
+                        id: SESSION_KEYSTONE_POLICY.DEFAULT_POOL.ID,
+                        salt: await getUUID(),
+                        type: SESSION_KEYSTONE_POLICY.COMMON.TYPE,
+                        algo: SESSION_KEYSTONE_POLICY.COMMON.ALGO,
+                        rounds: SESSION_KEYSTONE_POLICY.COMMON.ROUNDS,
+                        behavior: {
+                            size: SESSION_KEYSTONE_POLICY.DEFAULT_POOL.SIZE,
+                            replenish: SESSION_KEYSTONE_POLICY.COMMON.REPLENISH,
+                            selectSequentially: SESSION_KEYSTONE_POLICY.DEFAULT_POOL.SELECT_SEQUENTIALLY,
+                            selectRandomly: SESSION_KEYSTONE_POLICY.DEFAULT_POOL.SELECT_RANDOMLY,
+                            targetBindingChars: SESSION_KEYSTONE_POLICY.DEFAULT_POOL.TARGET_BINDING_CHARS,
+                        },
+                        allowedVerbs: [],
+                    },
+                    {
+                        id: SESSION_KEYSTONE_POLICY.HANDSHAKE_POOL.ID,
+                        salt: await getUUID(),
+                        type: SESSION_KEYSTONE_POLICY.COMMON.TYPE,
+                        algo: SESSION_KEYSTONE_POLICY.COMMON.ALGO,
+                        rounds: SESSION_KEYSTONE_POLICY.COMMON.ROUNDS,
+                        behavior: {
+                            size: SESSION_KEYSTONE_POLICY.HANDSHAKE_POOL.SIZE,
+                            replenish: SESSION_KEYSTONE_POLICY.COMMON.REPLENISH,
+                            selectSequentially: SESSION_KEYSTONE_POLICY.HANDSHAKE_POOL.SELECT_SEQUENTIALLY,
+                            selectRandomly: SESSION_KEYSTONE_POLICY.HANDSHAKE_POOL.SELECT_RANDOMLY,
+                            targetBindingChars: SESSION_KEYSTONE_POLICY.HANDSHAKE_POOL.TARGET_BINDING_CHARS,
+                        },
+                        allowedVerbs: [SESSION_KEYSTONE_POLICY.HANDSHAKE_POOL.VERB],
+                    }
+                ],
+                metaspace,
+                space,
+                frameDetails: {
+                    client: 'space-gib-web-session',
+                    target_I: domainI ? getIbGibAddr({ ibGib: domainI }) : undefined,
+                    target_X: targetX ? getIbGibAddr({ ibGib: targetX }) : undefined,
+                }
+            });
+
+            const sAddr = getIbGibAddr({ ibGib: sIbGib });
+            debugState.sessionS = sIbGib;
+            debugState.sessionSecret = sessionSecret;
+
+            devLog(`✓ Created Session Keystone: ${sAddr}`);
+            btn.textContent = '✓ Session Keystone Created';
+
+            // Enable next step
+            const nextBtn = document.getElementById('btn-evolve-domain-keystone') as HTMLButtonElement;
+            if (nextBtn) nextBtn.disabled = false;
+        } catch (error) {
+            devLog(`✗ ${extractErrorMsg(error)}`);
+            console.error(`${lc_fn} ${extractErrorMsg(error)}`);
+        }
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Evolve Domain Keystone (I^I1) button
+// ---------------------------------------------------------------------------
+
+function initEvolveDomainKeystoneButton(): void {
+    const lc_fn = `${lc}[initEvolveDomainKeystoneButton]`;
+    const btn = document.getElementById('btn-evolve-domain-keystone') as HTMLButtonElement | null;
+    if (!btn) {
+        console.warn(`${lc_fn} btn-evolve-domain-keystone not found — skipping`);
+        return;
+    }
+
+    btn.addEventListener('click', async () => {
+        try {
+            btn.disabled = true;
+            devLog('Evolving Domain Keystone (I^I1) with sync claim...');
+
+            const domainI = debugState.domainI;
+            const masterSecret = debugState.domainIMasterSecret;
+            const sessionS = debugState.sessionS;
+
+            if (!domainI || !masterSecret) { devLog('⚠ No domain keystone (I) found. Please Create Domain Keystone first.'); return; }
+            if (!sessionS) { devLog('⚠ No session keystone (S) found. Please Create Session Keystone first.'); return; }
+
+            const metaspace = await getGlobalMetaspace_waitIfNeeded();
+            const space = await metaspace.getLocalUserSpace({});
+            if (!space) { throw new Error("No default space found in metaspace."); }
+
+            const keystoneService = new KeystoneService_V1();
+            const sAddr = getIbGibAddr({ ibGib: sessionS });
+
+            devLog('Solving challenges to authorize sync...');
+            const evolvedI = await keystoneService.sign({
+                latestKeystone: domainI,
+                masterSecret,
+                claim: {
+                    target: sAddr,
+                    verb: 'sync'
+                },
+                metaspace,
+                space
+            });
+
+            const evolvedAddr = getIbGibAddr({ ibGib: evolvedI });
+            devLog(`✓ Local evolution complete: ${evolvedAddr}`);
+
+            // Update state with new tip
+            debugState.domainI = evolvedI;
+
+            devLog('Posting evolution to server...');
+            const apiBridge = new SpaceGibApiBridge();
+            // We pass the domain address (from the original TJP) and the session keystone
+            const domainAddr = getIbGibAddr({ ibGib: domainI });
+            const resSync = await apiBridge.putEvolveKeystone(domainAddr, evolvedI, [sessionS]);
+
+            if (!resSync.success) {
+                devLog(`✗ Server rejected evolution: ${resSync.message}`);
+                btn.disabled = false;
+                return;
+            }
+
+            devLog('✓ Server accepted Domain Keystone evolution!');
+            btn.textContent = '✓ Domain Keystone Evolved';
+
+            // Enable next step
+            const nextBtn = document.getElementById('btn-perform-sync') as HTMLButtonElement;
+            if (nextBtn) nextBtn.disabled = false;
+
+        } catch (error) {
+            devLog(`✗ ${extractErrorMsg(error)}`);
+            console.error(`${lc_fn} ${extractErrorMsg(error)}`);
+            btn.disabled = false;
+        }
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Perform Sync Handshake (S) button
+// ---------------------------------------------------------------------------
+
+function initPerformSyncButton(): void {
+    const lc_fn = `${lc}[initPerformSyncButton]`;
+    const btn = document.getElementById('btn-perform-sync') as HTMLButtonElement | null;
+    if (!btn) return;
+
+    btn.addEventListener('click', async () => {
+        try {
+            debugger; // walk through sync
+            btn.disabled = true;
+            devLog('Initiating Sync Handshake via WebSocket...');
+
+            const sessionS = debugState.sessionS;
+            const sessionSecret = debugState.sessionSecret;
+            const domainI = debugState.domainI;
+
+            if (!sessionS || !sessionSecret || !domainI) {
+                devLog('⚠ Incomplete state. Please complete steps 1-4.');
+                btn.disabled = false;
+                return;
+            }
+
+            const metaspace = await getGlobalMetaspace_waitIfNeeded();
+            const space = await metaspace.getLocalUserSpace({});
+            if (!space) { throw new Error("No space."); }
+
+            devLog('Pre-solving upfront picket-fence challenge...');
+            const handshakePool = (sessionS.data?.challengePools ?? []).find(p => p.id === SESSION_KEYSTONE_POLICY.HANDSHAKE_POOL.ID);
+            if (!handshakePool) {
+                throw new Error(`Session keystone missing "${SESSION_KEYSTONE_POLICY.HANDSHAKE_POOL.ID}" pool`);
+            }
+
+            const { challengeId } = getHandshakeChallenge(sessionS);
+            const strategy = KeystoneStrategyFactory.create({ config: handshakePool.config });
+            const poolSecret = await strategy.derivePoolSecret({ masterSecret: sessionSecret });
+            const solution = await strategy.generateSolution({
+                poolSecret,
+                poolId: SESSION_KEYSTONE_POLICY.HANDSHAKE_POOL.ID,
+                challengeId
+            });
+
+            const sAddr = getIbGibAddr({ ibGib: sessionS });
+            const domainAddr = getIbGibAddr({ ibGib: domainI });
+            const protocol = location.protocol === 'https:' ? 'wss:' : 'ws:';
+            const wsUrl = `${protocol}//${location.host}/api/sync/ws/${encodeURIComponent(domainAddr)}` +
+                `?sAddr=${encodeURIComponent(sAddr)}` +
+                `&solution=${solution.value}`;
+
+            devLog(`→ connecting to ${wsUrl}`);
+            const ws = new WebSocket(wsUrl);
+
+            ws.addEventListener('open', () => {
+                devLog('✓ WebSocket connected. Waiting for server challenge...');
+            });
+
+            ws.addEventListener('message', async (ev) => {
+                try {
+                    const msg = JSON.parse(ev.data);
+                    devLog(`← received: ${msg.type ?? 'message'}`);
+
+                    if (msg.type === 'auth-challenge-init') {
+                        devLog('→ sending auth-init with sAddr...');
+                        ws.send(JSON.stringify({
+                            type: 'auth-init',
+                            sAddr: getIbGibAddr({ ibGib: sessionS })
+                        }));
+                    } else if (msg.type === 'auth-challenge') {
+                        const { challengeUuid, demandedIds } = msg;
+                        devLog(`→ server demanded ${demandedIds.length} ids. Signing handshake proof...`);
+
+                        const keystoneService = new KeystoneService_V1();
+                        const proofFrame = await keystoneService.sign({
+                            latestKeystone: sessionS,
+                            masterSecret: sessionSecret,
+                            poolId: 'handshake',
+                            requiredChallengeIds: demandedIds,
+                            claim: {
+                                verb: 'handshake',
+                                target: challengeUuid
+                            },
+                            metaspace,
+                            space
+                        });
+
+                        devLog('→ sending auth-proof...');
+                        ws.send(JSON.stringify({
+                            type: 'auth-proof',
+                            proofFrame
+                        }));
+                    } else if (msg.type === 'auth-ok') {
+                        devLog('✓ Handshake SUCCESS! Sync session authorized.');
+                        btn.textContent = '✓ Sync Authorized';
+                    } else if (msg.type === 'auth-fail') {
+                        devLog(`✗ Handshake FAILED: ${msg.message}`);
+                        btn.disabled = false;
+                    }
+                } catch (error) {
+                    devLog(`✗ Message handler error: ${extractErrorMsg(error)}`);
+                    console.error(`${lc_fn} Message handler error:`, error);
+                    btn.disabled = false;
+                }
+            });
+
+            ws.addEventListener('close', (ev) => {
+                devLog(`✗ WebSocket closed (code ${ev.code})`);
+                btn.disabled = false;
+            });
+
+            ws.addEventListener('error', () => {
+                devLog(`✗ WebSocket error — check server`);
+                btn.disabled = false;
+            });
+
+        } catch (error) {
+            devLog(`✗ ${extractErrorMsg(error)}`);
+            console.error(`${lc_fn} ${extractErrorMsg(error)}`);
+            btn.disabled = false;
+        }
+    });
+}
+
+// ---------------------------------------------------------------------------
+// Dev Tools UI Init
+// ---------------------------------------------------------------------------
+
+/**
+ * Call once inside DOMContentLoaded to wire up all dev-tool buttons.
+ */
+export function initDevTools(): void {
+    const lc_fn = `${lc}[initDevTools]`;
+    try {
+        initPrintStateButton();
+        initCreateDomainKeystoneButton();
+        initWsTestButton();
+        initCreateTestIbGibButton();
+        initCreateSessionKeystoneButton();
+        initEvolveDomainKeystoneButton();
+        initPerformSyncButton();
+    } catch (error) {
+        console.error(`${lc_fn} ${extractErrorMsg(error)}`);
+    }
+}