@ibgib/space-gib 0.0.3 → 0.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ibgib/space-gib",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "type": "module",
   "description": "ibgib storage and provider service — SaaS at ibgib.space",
   "scripts": {
@@ -12,11 +12,11 @@
     "build:test": "tsc -p tsconfig.test.json"
   },
   "dependencies": {
-    "@ibgib/core-gib": "*",
-    "@ibgib/helper-gib": "*",
-    "@ibgib/ts-gib": "*",
-    "@ibgib/web-gib": "*",
-    "@ibgib/node-gib": "*"
+    "@ibgib/core-gib": "^0.1.62",
+    "@ibgib/helper-gib": "^0.0.36",
+    "@ibgib/ts-gib": "^0.5.32",
+    "@ibgib/web-gib": "^0.0.48",
+    "@ibgib/node-gib": "^0.0.6"
   },
   "engines": {
     "node": ">=20.0.0"

package/src/client/AUTO-GENERATED-version.mts

@@ -8,4 +8,4 @@
 /**
  * Version of space-gib, auto-updated by the build process.
  */
-export const AUTO_GENERATED_VERSION = '0.0.3';
+export const AUTO_GENERATED_VERSION = '0.0.5';

package/src/client/components/identity-header/IMPLEMENTATION.md

@@ -0,0 +1,45 @@
+# Identity Header Component - Implementation Spec
+
+This document details the layout, styling, and behavior for the `identity-header` component (`ibgib-identity-header`). It is rendered inside the app shell's header and acts as a status indicator and shortcut route for the user's active identity.
+
+## Requirements
+
+1. **State-Driven Display**:
+   - **Active Identity Mode**: If an active Domain Identity (Keystone) address exists in settings and is resolved in the local space, the component displays an identity pill showing a truncated version of the address.
+   - **Inactive/Default Mode**: If no identity is resolved, the component renders a prominent "Create Identity" button.
+2. **Interactive Routing**:
+   - Clicking either the identity pill or the fallback "Create Identity" button calls `SpaceGibShellService.showIdentityManager()` to load the full `<ibgib-identity-manager>` component in the center view panel.
+3. **Agent-Themeable Styles**:
+   - The layout must be highly compact to fit inside a standard horizontal header panel.
+   - All styling must prioritize valid theme CSS variables (e.g., `--button-background-color-base`, `--tab-text-color-active`) to remain dynamic and styleable by runtime agents.
+4. **Shared Settings Scope**:
+   - It is initialized with the virtual `ROOT_ADDR` and manually binds to the `"keystones"` index `ibgib`.
+   - It initializes its coupled settings via `this.initSettings()`. Since both this component and the manager share the `"keystones"` index backing model, they automatically resolve the exact same coupled settings `ibgib` and settings timeline, reactively syncing active identity selection changes.
+   - For detailed data schema, see [identity-manager IMPLEMENTATION.md](../identity-manager/IMPLEMENTATION.md).
+
+---
+
+## Component Structure
+
+* **[identity-header.mts](file:///c:/Users/billm/antigravity/ibgib/apps/space-gib/src/client/components/identity-header/identity-header.mts)**: Element definition, lifecycle events, active identity resolution, shell service navigation call.
+* **[identity-header.html](file:///c:/Users/billm/antigravity/ibgib/apps/space-gib/src/client/components/identity-header/identity-header.html)**: Compact HTML structures for the pill and fallback button.
+* **[identity-header.css](file:///c:/Users/billm/antigravity/ibgib/apps/space-gib/src/client/components/identity-header/identity-header.css)**: Glassmorphic pill styling matching current themes.
+
+---
+
+## Implementation Checklist
+
+### Phase 1: Basic Scaffolding & Setup
+- [x] Scaffold `identity-header.mts`, `.html`, and `.css` files.
+- [x] Register `IdentityHeaderComponentMeta` with `IbGibComponentService`.
+- [x] Mount `<ibgib-identity-header>` inside the header panel in `SpaceGibShellService`.
+
+### Phase 2: Navigation & Identity State
+- [x] Wire up click handlers to trigger center-panel navigation to `ibgib-identity-manager`.
+- [x] Resolve settings and check the `"keystones"` index to render the appropriate active/inactive view mode.
+
+### Phase 3: Visual Polish & Bugs
+- [ ] Ensure the header component has an initial size/button and is visible while the page is initializing.
+
+### Testing Note
+- [ ] **Manual Testing Only**: Visual integration and navigation behavior will be verified manually by the developer to limit token consumption.

package/src/client/components/identity-header/identity-header.css

@@ -0,0 +1,74 @@
+:host {
+    display: inline-block;
+    vertical-align: middle;
+}
+
+.header-widget-container {
+    display: flex;
+    align-items: center;
+    justify-content: flex-end;
+}
+
+/* Glassmorphic identity status pill */
+.identity-pill {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    padding: 0.4rem 0.8rem;
+    background: var(--tab-background-color-active, rgba(255, 255, 255, 0.1));
+    border: 1px solid var(--tab-border-color-active, rgba(80, 250, 123, 0.3));
+    border-radius: var(--radius-lg, 20px);
+    cursor: pointer;
+    transition: all 0.2s ease-in-out;
+}
+
+.identity-pill:hover {
+    background: rgba(80, 250, 123, 0.15);
+    border-color: var(--clr-accent, #50fa7b);
+    transform: translateY(-1px);
+    box-shadow: 0 2px 8px rgba(80, 250, 123, 0.1);
+}
+
+.avatar-circle {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 24px;
+    height: 24px;
+    border-radius: 50%;
+    font-size: 0.85rem;
+    font-weight: 700;
+    text-transform: uppercase;
+    background: var(--clr-accent, #50fa7b);
+    color: #11111b;
+    flex-shrink: 0;
+}
+
+.address-text {
+    font-family: var(--font-sans, sans-serif);
+    font-size: 0.85rem;
+    color: var(--clr-text-primary, #ffffff);
+    font-weight: 500;
+}
+
+/* Fallback button when no identity is loaded */
+.action-btn {
+    padding: 0.4rem 0.9rem;
+    border-radius: 20px;
+    font-size: 0.8rem;
+    background: transparent;
+    border: 1px dashed var(--clr-warn, #ffcc44);
+    color: var(--clr-warn, #ffcc44);
+    cursor: pointer;
+    transition: all 0.2s ease-in-out;
+}
+
+.action-btn:hover {
+    background: rgba(255, 204, 68, 0.1);
+    border-color: var(--clr-warn, #ffcc44);
+    box-shadow: 0 0 8px rgba(255, 204, 68, 0.2);
+}
+
+.hidden {
+    display: none !important;
+}

package/src/client/components/identity-header/identity-header.html

@@ -0,0 +1,10 @@
+<div id="container" class="header-widget-container">
+    <!-- Active Identity Pill -->
+    <div id="active-identity-pill" class="identity-pill hidden" title="Active Domain Identity. Click to manage.">
+        <div id="identity-avatar" class="avatar-circle">-</div>
+        <span id="identity-address-truncated" class="address-text">No Identity</span>
+    </div>
+
+    <!-- Fallback Action Button -->
+    <button id="btn-create-identity" class="action-btn hidden" title="No active identity. Click to manage.">No Active Identity</button>
+</div>

package/src/client/components/identity-header/identity-header.mts

@@ -0,0 +1,361 @@
+import thisCss from "./identity-header.css";
+import thisHtml from "./identity-header.html";
+import styleCss from "../../style.css";
+
+import { IbGibAddr } from "@ibgib/ts-gib/dist/types.mjs";
+import { IbGib_V1 } from "@ibgib/ts-gib/dist/V1/types.mjs";
+import { getIbGibAddr } from "@ibgib/ts-gib/dist/helper.mjs";
+import { ROOT_ADDR } from "@ibgib/ts-gib/dist/V1/constants.mjs";
+import { extractErrorMsg } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+import {
+    IbGibDynamicComponentMetaBase, IbGibDynamicComponentInstanceBase,
+} from "@ibgib/web-gib/dist/ui/component/ibgib-dynamic-component-bases.mjs";
+import {
+    ElementsBase, IbGibDynamicComponentInstance,
+    IbGibDynamicComponentInstanceInitOpts,
+} from "@ibgib/web-gib/dist/ui/component/component-types.mjs";
+import { SettingsType } from "@ibgib/web-gib/dist/common/settings/settings-constants.mjs";
+import { Settings_General } from "@ibgib/web-gib/dist/common/settings/settings-types.mjs";
+
+import { getComponentCtorArg, getIbGibGlobalThis_SpaceGib } from "../../helpers.web.mjs";
+import { APP_CONFIG } from "../../constants.mjs";
+import { getSpaceGibShellSvc } from "../../ui/shell/space-gib-shell-service.mjs";
+import { devLog } from "../../dev-tools.mjs";
+import { KeystoneService_V1 } from "@ibgib/core-gib/dist/keystone/keystone-service-v1.mjs";
+import { KeystoneIbGib_V1 } from "@ibgib/core-gib/dist/keystone/keystone-types.mjs";
+import { getDeterministicColorInfo } from "@ibgib/web-gib/dist/helpers.mjs";
+import { EVENT_IBGIB_IDENTITY_REQUEST_CHANGE, EVENT_IBGIB_IDENTITY_CHANGED } from "@ibgib/web-gib/dist/ui/ui-constants.mjs";
+
+export const IDENTITY_HEADER_COMPONENT_NAME = 'ibgib-identity-header';
+
+/**
+ * Metadata for the Identity Header component.
+ */
+export class IdentityHeaderComponentMeta extends IbGibDynamicComponentMetaBase {
+    protected lc: string = `[IdentityHeaderComponentMeta]`;
+
+    routeRegExp?: RegExp = new RegExp(`^${IDENTITY_HEADER_COMPONENT_NAME}$`);
+    componentName = IDENTITY_HEADER_COMPONENT_NAME;
+
+    constructor() {
+        super(getComponentCtorArg());
+        if (!customElements.get(this.componentName)) {
+            customElements.define(this.componentName, IdentityHeaderComponentInstance);
+        }
+    }
+
+    async createInstance({
+        path,
+        ibGibAddr
+    }: {
+        path: string;
+        ibGibAddr: IbGibAddr;
+    }): Promise<IbGibDynamicComponentInstance> {
+        const component = document.createElement(this.componentName) as IdentityHeaderComponentInstance;
+        await component.initialize({
+            ibGibAddr,
+            meta: this,
+            html: thisHtml,
+            css: [styleCss, thisCss],
+        });
+        return component;
+    }
+}
+
+/**
+ * References to DOM elements within the component's shadow root.
+ */
+interface IdentityHeaderElements extends ElementsBase {
+    containerEl: HTMLDivElement;
+    activeIdentityPillEl: HTMLDivElement;
+    identityAddressTruncatedEl: HTMLSpanElement;
+    btnCreateIdentityEl: HTMLButtonElement;
+    identityAvatarEl: HTMLDivElement;
+}
+
+/**
+ * Concrete implementation of the Identity Header component.
+ */
+export class IdentityHeaderComponentInstance
+    extends IbGibDynamicComponentInstanceBase<IbGib_V1, IdentityHeaderElements>
+    implements IbGibDynamicComponentInstance<IbGib_V1, IdentityHeaderElements> {
+
+    protected lc: string = `[IdentityHeaderComponentInstance]`;
+    private activeAddr: string | null = null;
+    private _onRequestIdentityChange: ((e: any) => void) | null = null;
+    private keystoneCache: Map<string, { username: string, description: string }> = new Map();
+
+    constructor() {
+        super();
+    }
+
+    private async getKeystoneDetails(addr: string): Promise<{ username: string, description: string }> {
+        const cached = this.keystoneCache.get(addr);
+        if (cached) return cached;
+
+        const metaspace = getIbGibGlobalThis_SpaceGib(APP_CONFIG).metaspace;
+        if (!metaspace) return { username: '', description: '' };
+        const space = await metaspace.getLocalUserSpace({ lock: false });
+        if (!space) return { username: '', description: '' };
+
+        try {
+            const res = await metaspace.get({ addr, space });
+            if (res.success && res.ibGibs && res.ibGibs.length > 0) {
+                const keystone = res.ibGibs[0] as KeystoneIbGib_V1;
+                const keystoneSvc = new KeystoneService_V1();
+                const aggregated = await keystoneSvc.getAggregateDetails({
+                    latestKeystone: keystone,
+                    metaspace,
+                    space
+                });
+                const username = aggregated?.username || aggregated?.profile?.name || aggregated?.name || '';
+                const description = aggregated?.description || aggregated?.profile?.description || '';
+                const details = { username, description };
+                this.keystoneCache.set(addr, details);
+                return details;
+            }
+        } catch (err) {
+            console.warn(`Error getting details for keystone ${addr}: ${extractErrorMsg(err)}`);
+        }
+
+        return { username: '', description: '' };
+    }
+
+
+    override async initialize(opts: IbGibDynamicComponentInstanceInitOpts): Promise<void> {
+        await super.initialize(opts);
+    }
+
+    override async created(): Promise<void> {
+        this.elements = {} as IdentityHeaderElements;
+
+        const shadow = this.shadowRoot!;
+        this.elements.containerEl = shadow.getElementById('container') as HTMLDivElement;
+        this.elements.activeIdentityPillEl = shadow.getElementById('active-identity-pill') as HTMLDivElement;
+        this.elements.identityAddressTruncatedEl = shadow.getElementById('identity-address-truncated') as HTMLSpanElement;
+        this.elements.btnCreateIdentityEl = shadow.getElementById('btn-create-identity') as HTMLButtonElement;
+        this.elements.identityAvatarEl = shadow.getElementById('identity-avatar') as HTMLDivElement;
+
+        // Required contentEl mapping
+        this.elements.contentEl = this.elements.containerEl;
+
+        this.initHandlers();
+
+        // Subscribe to global active identity request changes
+        this._onRequestIdentityChange = (e: any) => this.handleRequestIdentityChange(e);
+        window.addEventListener(EVENT_IBGIB_IDENTITY_REQUEST_CHANGE, this._onRequestIdentityChange);
+
+        if (this.ibGibAddr === ROOT_ADDR || !this.ibGib) {
+            await this.loadKeystonesIndex();
+        } else {
+            await this.initSettings();
+        }
+        await this.renderUI();
+    }
+
+    private async loadKeystonesIndex(): Promise<void> {
+        const lc = `${this.lc}[loadKeystonesIndex]`;
+        try {
+            const metaspace = getIbGibGlobalThis_SpaceGib(APP_CONFIG).metaspace;
+            if (!metaspace) { return; }
+            const space = await metaspace.getLocalUserSpace({ lock: false });
+            if (!space) { return; }
+            const keystonesIndex = await metaspace.getSpecialIbGib({
+                type: "keystones",
+                space,
+                initialize: true,
+            });
+            if (keystonesIndex) {
+                this.ibGibAddr = getIbGibAddr({ ibGib: keystonesIndex });
+                await this.loadIbGib();
+                await this.initSettings();
+            }
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+        }
+    }
+
+    override async disconnected(): Promise<void> {
+        if (this._onRequestIdentityChange) {
+            window.removeEventListener(EVENT_IBGIB_IDENTITY_REQUEST_CHANGE, this._onRequestIdentityChange);
+        }
+    }
+
+    private initHandlers() {
+        // Handle clicks: route to the full identity manager
+        this.elements!.activeIdentityPillEl.addEventListener('click', () => this.navigateToManager());
+        this.elements!.btnCreateIdentityEl.addEventListener('click', () => this.navigateToManager());
+    }
+
+    private navigateToManager() {
+        const shellSvc = getSpaceGibShellSvc();
+        // Route to center view identity manager
+        shellSvc.showIdentityManager();
+    }
+
+    /**
+     * Resolves the active identity from settings and verifies it exists in the keystones index.
+     */
+    private async resolveActiveIdentity() {
+        const lc = `${this.lc}[resolveActiveIdentity]`;
+        try {
+            if (!this.settings) {
+                this.activeAddr = null;
+                const globalState = getIbGibGlobalThis_SpaceGib(APP_CONFIG);
+                globalState.identity = undefined;
+                return;
+            }
+            const generalSettings = await this.getSettings<Settings_General>({
+                settingsType: SettingsType.general,
+                useCase: 'current',
+            });
+            const activeAddrInSettings = (generalSettings as any)?.activeIdentityAddr;
+
+            // Verify it is actually one of the registered keystones in the index relations
+            const registeredKeystones = this.ibGib?.rel8ns?.keystone ?? [];
+            if (activeAddrInSettings && registeredKeystones.includes(activeAddrInSettings)) {
+                this.activeAddr = activeAddrInSettings;
+            } else if (registeredKeystones.length > 0) {
+                this.activeAddr = registeredKeystones[0];
+            } else {
+                this.activeAddr = null;
+            }
+
+            // Sync with globalState.identity
+            const globalState = getIbGibGlobalThis_SpaceGib(APP_CONFIG) as any;
+            if (this.activeAddr) {
+                const metaspace = globalState.metaspace;
+                if (metaspace) {
+                    const space = await metaspace.getLocalUserSpace({ lock: false });
+                    if (space) {
+                        const res = await metaspace.get({ addr: this.activeAddr, space });
+                        if (res.success && res.ibGibs && res.ibGibs.length > 0) {
+                            globalState.identity = res.ibGibs[0];
+                        }
+                    }
+                }
+            } else {
+                globalState.identity = undefined;
+            }
+        } catch (error) {
+            console.error(`${lc} ${extractErrorMsg(error)}`);
+            this.activeAddr = null;
+            const globalState = getIbGibGlobalThis_SpaceGib(APP_CONFIG) as any;
+            globalState.identity = undefined;
+        }
+    }
+
+    protected override async renderUI(): Promise<void> {
+        if (!this.elements) return;
+
+        // Double check state on render
+        await this.resolveActiveIdentity();
+
+        if (this.activeAddr) {
+            this.elements.activeIdentityPillEl.classList.remove('hidden');
+            this.elements.btnCreateIdentityEl.classList.add('hidden');
+
+            const addr = this.activeAddr;
+
+            // Initial fallback render
+            let displayAddr = addr;
+            if (displayAddr.length > 14) {
+                displayAddr = displayAddr.substring(0, 7) + '...' + displayAddr.substring(displayAddr.length - 5);
+            }
+            this.elements.identityAddressTruncatedEl.textContent = displayAddr;
+            this.elements.identityAvatarEl.textContent = '-';
+            this.elements.identityAvatarEl.style.backgroundColor = 'var(--clr-accent)';
+            this.elements.identityAvatarEl.style.color = '#11111b';
+            this.elements.activeIdentityPillEl.title = `Active Identity: ${addr}\nClick to manage.`;
+
+            // Load details dynamically
+            const details = await this.getKeystoneDetails(addr);
+
+            // First letter of username, or fallback to first char of address (or 'A')
+            let letter = '-';
+            if (details.username) {
+                letter = details.username.charAt(0).toUpperCase();
+            } else {
+                const match = addr.match(/[a-zA-Z]/);
+                letter = match ? match[0].toUpperCase() : 'I';
+            }
+            if (!this.elements) { throw new Error(`(UNEXPECTED) this.elements falsy? (E: fd6bfa87c968a38c4860588818c3cd26)`); }
+
+            this.elements.identityAvatarEl.textContent = letter;
+
+            // Colorize avatar deterministically based on cryptographic gib
+            const colorInfo = getDeterministicColorInfo({ ibGibAddr: addr });
+            const bg = colorInfo.tjpColor || colorInfo.punctiliarColor;
+            const fg = colorInfo.tjpColorContrast || colorInfo.punctiliarColorContrast;
+            this.elements.identityAvatarEl.style.backgroundColor = bg;
+            this.elements.identityAvatarEl.style.color = fg;
+
+            // Set user display name or address in pill
+            let displayName = details.username;
+            const maxLen = 14;
+            if (displayName) {
+                if (displayName.length > maxLen) {
+                    displayName = displayName.substring(0, maxLen - 3) + '...';
+                }
+                this.elements.identityAddressTruncatedEl.textContent = displayName;
+            }
+
+            // Title with full details
+            const titleParts: string[] = [];
+            if (details.username) {
+                titleParts.push(`User: ${details.username}`);
+            }
+            if (details.description) {
+                const desc = details.description.length > 100
+                    ? details.description.substring(0, 97) + '...'
+                    : details.description;
+                titleParts.push(`Desc: ${desc}`);
+            }
+            titleParts.push(`Addr: ${addr}`);
+            titleParts.push(`Click to manage.`);
+            this.elements.activeIdentityPillEl.title = titleParts.join('\n');
+        } else {
+            this.elements.activeIdentityPillEl.classList.add('hidden');
+            this.elements.btnCreateIdentityEl.classList.remove('hidden');
+        }
+    }
+
+    private async handleRequestIdentityChange(e: any) {
+        const lc = `${this.lc}[handleRequestIdentityChange]`;
+        const addr = e.detail?.activeIdentityAddr;
+        if (!addr) return;
+        devLog(`${lc} Request to change active identity to: ${addr}`);
+        try {
+            if (!this.settings) return;
+            const generalSettings = await this.getSettings<Settings_General>({
+                settingsType: SettingsType.general,
+                useCase: 'current',
+            }) ?? { type: 'general' };
+
+            (generalSettings as any).activeIdentityAddr = addr;
+
+            await this.updateSettings({
+                settingsType: SettingsType.general,
+                useCase: 'current',
+                newSectionInfo: generalSettings,
+            });
+
+            await this.resolveActiveIdentity();
+            await this.renderUI();
+
+            // Dispatch EVENT_IBGIB_IDENTITY_CHANGED
+            window.dispatchEvent(new CustomEvent(EVENT_IBGIB_IDENTITY_CHANGED, {
+                detail: { activeIdentityAddr: addr },
+                bubbles: true,
+                composed: true
+            }));
+            devLog(`${lc} Successfully changed active identity settings to: ${addr}`);
+        } catch (error) {
+            console.error(`${lc} Failed to switch active identity: ${extractErrorMsg(error)}`);
+        }
+    }
+
+    override async handleContextUpdated(): Promise<void> {
+        await this.renderUI();
+    }
+}

package/src/client/components/identity-manager/IMPLEMENTATION.md

@@ -0,0 +1,100 @@
+# Identity Manager Component - Implementation Spec
+
+This document maps the implementation details for the reusable `identity-manager` component (`ibgib-identity-manager`). While developed initially inside `space-gib` as a reference implementation, it is designed to be highly decoupled and may eventually migrate down to `web-gib` for use in other downstream applications.
+
+## Core Architecture (Separation of App and Data)
+
+We advocate for a strict separation of **applications** and **data providers**:
+- **Local-First & Sync-Based**: Applications run local-first, storing user data in a local space and syncing peer-to-peer with remote data spaces/hosts via the `sync-gib` protocol.
+- **Auditable Keystone Identity**: Identity is represented by a **Domain Keystone ($I$)**—a verifiable, historical timeline of challenge-reveals. Authentication is performed by walking and verifying the evolution history of the keystone timeline.
+  - *Note on Pricing/Gas:* While the core identity protocol does not require transaction fees, downstream apps/hosts are free to implement pricing plans or gas-like charging mechanisms per node.
+- **Verification Flexibility**: In V1, the verification strategy is strictly `hash-reveal-v1`. However, the keystone architecture is designed as a generic audit log. Future challenge types could wrap cryptographic certificates, witness testimonies, or simple/trivial challenges.
+- **SSO & Custodian Delegation**: Integration with external OAuth2 providers (e.g., Google Sign-In) is a key requirement. This will likely involve delegating a "custodian status" to the hosting server/app node, allowing it to perform authorized managerial mutations on the identity timeline on behalf of the user. The cryptographic implementation details of this delegation are TBD and will be designed after the front-end is established.
+- **Delegated Authority**: To sync data, the Domain Keystone is evolved once per session to delegate signing authority to a short-lived **Session Keystone ($S$)**. The Session Keystone targets the remote storage space, solving challenges to authorize specific read/write operations without exposing the root master secrets.
+- **Backing Index & Coupling**: When initialized with a virtual address (`ROOT_ADDR`), the component manually retrieves and binds to the `"keystones"` special index `ibgib` from the local space. It also initializes and couples a local settings `ibgib` using `this.initSettings()`.
+- **Settings-driven Active Selection:** The user's active identity address is stored inside the coupled settings `ibgib` under the `general` section (`SettingsType.general`). Tab switching updates this setting reactively. Since other components (like `<ibgib-identity-header>`) bind to the same `"keystones"` index and share its settings scope, they reactively adapt to updates on the settings timeline.
+
+---
+
+## Component Role & Hierarchy
+
+The `identity-manager` functions as a tabbed/list parent component (extending `IbGibDynamicComponentInstanceBase_ParentOfTabs` or `IbGibDynamicComponentInstanceBase_Parent`) that manages one or more Domain Identities:
+
+1. **Identity List & Selection**:
+   - Renders a list of loaded/configured Domain Identities from the `"keystones"` index relation `"keystone"`.
+   - Leverages tab/list activation plumbing to switch between active identities.
+   - Saves and restores the active primary identity in the `general` settings section via `this.updateSettings()`.
+2. **Identity Creator (Child Component)**:
+   - If no identity is loaded or created, it dynamically mounts the generic `ibgib-keystone-creator` component to generate a new Genesis Keystone or import one via a master secret.
+3. **Identity Explorer / Raw Viewer**:
+   - For any selected identity, provides a "Raw View" tab/accordion.
+   - This embeds a raw explorer similar to the `ibgib-raw` component (`apps/blank-gib/src/components/common/raw/`) to display the raw JSON of the keystone frames and trace their evolutionary lineage.
+4. **Active Sync & Replicas Control**:
+   - Displays the active primary sync channel and session delegation status.
+   - Provides options to register additional remote space URLs as replicas (structured similarly to how a package manager configures repositories). V1 focuses on a single active sync channel, with structural UI support for multiple future backup peers.
+   - *Investigation:* We will analyze whether and how to securely propagate/sync the identity itself to other providers using keystone evolution.
+
+---
+
+## Component Structure
+
+Following the custom `web-gib` Web Component microframework, the component consists of:
+
+* **[identity-manager.mts](file:///c:/Users/billm/antigravity/ibgib/apps/space-gib/src/client/components/identity-manager/identity-manager.mts)**: Element definition, lifecycle hooks (`initialize`, `created`, `renderUI`), event bindings, settings management, and integration with `KeystoneService_V1`.
+* **[identity-manager.html](file:///c:/Users/billm/antigravity/ibgib/apps/space-gib/src/client/components/identity-manager/identity-manager.html)**: Markup template for Shadow DOM injection.
+* **[identity-manager.css](file:///c:/Users/billm/antigravity/ibgib/apps/space-gib/src/client/components/identity-manager/identity-manager.css)**: Glassmorphic dark styling.
+
+---
+
+## Implementation Checklist
+
+### Phase 1: Basic Scaffolding & Setup
+- [x] Scaffold `identity-manager.mts`, `.html`, and `.css` files (Reference: [@.agents/skills/ibgib-create-component/SKILL.md](file:///c:/Users/billm/antigravity/ibgib/.agents/skills/ibgib-create-component/SKILL.md)).
+- [x] Register `IdentityManagerComponentMeta` with `IbGibComponentService`.
+- [x] Expose in `SpaceGibShellService` to load `<ibgib-identity-manager>`.
+
+### Phase 2: Identity List & Settings Integration
+- [x] Initialize the component settings to track loaded Domain Identity addresses.
+- [x] Implement UI tabs for switching between identities.
+- [x] Mount `ibgib-keystone-creator` as a child view if no identity exists.
+
+### Phase 3: Raw Explorer Integration
+- [x] Integrate a child details panel showing raw keystone JSON using patterns from the `ibgib-raw` component.
+- [x] Add a "Verify Chain" button executing `validateKeystoneTimeline` and reporting status.
+
+### Phase 4: Sync & Replication Setup
+- [x] Implement inputs to configure remote sync repositories (URLs) (currently disabled for V1).
+- [x] Add sync button triggering a delegation evolution and starting the sync sequence (currently disabled for V1).
+- [x] Document the custom `web-gib` Web Component microframework (covering element lifecycles, routing, parent-child delegation, and settings/tabs state persistence).
+
+### Phase 5: UI/UX Enhancements & Bugs
+- [x] Center/align the `<ibgib-identity-manager>` component instead of having it shoved to the left (maxing out at ~66% width of the center-panel).
+- [x] Adjust scrolling behavior so the entire manager or manager-content div scrolls, instead of limiting the scroll region to the accordion detail pre-tag.
+- [x] Automatically select/activate the newly created identity keystone in the tab list upon creation.
+
+### Phase 6: Detail Views (Pools & Keystone Metadata)
+- [x] Add a details view for challenge pools on the keystone (`KeystoneData_V1.challengePools`).
+- [x] Add display details for each of the main areas of the keystone included in `KeystoneData_V1` and core `IbGibData_V1` properties (e.g. `n`, `timestamp`, `uuid`, etc.).
+- [x] Support human-readable profile details (such as name, email, contact info) stored in `frameDetails` and aggregated via `checkpointDetails`/`getAggregateDetails()`.
+
+### Phase 7: Key-Value Details & History Scrubber
+- [x] Expand component max-width to fill the center panel (remove/adjust `max-width: 800px` on `:host`).
+- [x] Re-layout Domain Identity Details into an inverted key-value grid (Labels in Column 1, Values in Column 2).
+- [x] Add dedicated key-value rows for "Name" and "Description" in the details list.
+- [x] Add "Aggr. Details" displaying the aggregated details JSON in a formatted, scrollable pre-tag.
+- [x] Add "Frame Details" displaying the current frame's `frameDetails` JSON in a formatted, scrollable pre-tag.
+- [x] Implement history scrubber navigation (First, Back 10, Back 1, Next 1, Next 10, Latest) to traverse the keystone timeline.
+
+### Phase 8: Active Identity Management
+- [x] Define reusable event constants (`EVENT_IBGIB_IDENTITY_REQUEST_CHANGE` and `EVENT_IBGIB_IDENTITY_CHANGED`) in `libs/web-gib/src/ui/ui-constants.mts`.
+- [x] Add checkbox in `<ibgib-keystone-creator>` to make the newly created identity the active one. Enforce/lock to checked if no identities exist yet.
+- [x] If checked on creation, `<ibgib-keystone-creator>` dispatches `EVENT_IBGIB_IDENTITY_REQUEST_CHANGE` containing the new keystone address.
+- [x] Add "Set as Active Identity" button to `<ibgib-identity-manager>` details view. When clicked, it dispatches `EVENT_IBGIB_IDENTITY_REQUEST_CHANGE` with the selected keystone address.
+- [x] Decouple tab clicks in `<ibgib-identity-manager>` so they only browse details via `viewIdentityDetails(addr)` without setting active identity.
+- [x] Update `<ibgib-identity-header>` to listen for `EVENT_IBGIB_IDENTITY_REQUEST_CHANGE`. On receipt, write the address to its settings timeline, update `ibGibGlobalThis.identity`, re-render, and dispatch `EVENT_IBGIB_IDENTITY_CHANGED`.
+- [x] Set `ibGibGlobalThis.identity` on `<ibgib-identity-header>` initialization using settings.
+- [x] Update `<ibgib-identity-manager>` to subscribe to `EVENT_IBGIB_IDENTITY_CHANGED` and re-render/update its "Set as Active" button state accordingly.
+- [ ] TODO: Enhance the `<ibgib-identity-header>` component to support selecting/switching between loaded identities directly from a dropdown/dropdown-like UI inside the header.
+
+### Testing Protocol
+- [ ] **Manual Testing Only**: All interactive and visual validation will be performed manually by the user to avoid token overhead from screenshot/video processing.