@ibgib/web-gib 0.0.23 → 0.0.25

package/dist/AUTO-GENERATED-version.d.mts

@@ -0,0 +1,14 @@
+/**
+ * @module auto-generated-version
+ *
+ * CHANGES TO THIS FILE NOT BE SAVED
+ *
+ * this is automatically updated in the build process.
+ *
+ * CHANGES TO THIS FILE NOT BE SAVED
+ */
+/**
+ * this is the version of this package, auto-updated in the build process
+ */
+export declare const AUTO_GENERATED_VERSION = "0.0.25";
+//# sourceMappingURL=AUTO-GENERATED-version.d.mts.map

package/dist/AUTO-GENERATED-version.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AUTO-GENERATED-version.d.mts","sourceRoot":"","sources":["../src/AUTO-GENERATED-version.mts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;GAEG;AACH,eAAO,MAAM,sBAAsB,WAAW,CAAC"}

package/dist/AUTO-GENERATED-version.mjs

@@ -0,0 +1,14 @@
+/**
+ * @module auto-generated-version
+ *
+ * CHANGES TO THIS FILE NOT BE SAVED
+ *
+ * this is automatically updated in the build process.
+ *
+ * CHANGES TO THIS FILE NOT BE SAVED
+ */
+/**
+ * this is the version of this package, auto-updated in the build process
+ */
+export const AUTO_GENERATED_VERSION = '0.0.25';
+//# sourceMappingURL=AUTO-GENERATED-version.mjs.map

package/dist/AUTO-GENERATED-version.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"AUTO-GENERATED-version.mjs","sourceRoot":"","sources":["../src/AUTO-GENERATED-version.mts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,QAAQ,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ibgib/web-gib",
-  "version": "0.0.23",
+  "version": "0.0.25",
   "description": "Framework for creating agentic ibGib web apps. Contains plumbing for ibgib components, agentic framework (currently only Gemini implemented), web-based IndexedDB storage substrate, and more.",
   "funding": {
     "type": "individual",
@@ -12,6 +12,9 @@
   },
   "scripts": {
     "clean": "node node_modules/@ibgib/helper-gib/tools/clean.js ./dist",
+    "generate:src:version": "node ./tools/generate-version-file.js",
+    "generate:agent:skills": "node ./tools/copy-agent-skills.js",
+    "prebuild": "npm run generate:src:version && npm run generate:agent:skills",
     "build": "npm run clean && tsc -b tsconfig.json --force",
     "build:test": "npm run clean && tsc -b tsconfig.test.json --force",
     "build:test:noclean": "tsc -b tsconfig.test.json --force",

package/src/AUTO-GENERATED-version.mts

@@ -0,0 +1,14 @@
+/**
+ * @module auto-generated-version
+ *
+ * CHANGES TO THIS FILE NOT BE SAVED
+ *
+ * this is automatically updated in the build process.
+ *
+ * CHANGES TO THIS FILE NOT BE SAVED
+ */
+
+/**
+ * this is the version of this package, auto-updated in the build process
+ */
+export const AUTO_GENERATED_VERSION = '0.0.25';

package/tools/auto-generated-agent-skills/skills/ibgib-add-core-engine/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: ibgib-add-core-engine
+description: >
+  Scaffolds the foundational ibgib bootstrap flow and global state management.
+  Generates the 7 foundational files (index.html, index.mts, bootstrap.mts,
+  constants.mts, types.mts, helpers.web.mts, and style.css) required for an
+  ibgib app to boot. Supports both greenfield and brownfield projects.
+---
+
+# Skill: ibgib-add-core-engine
+
+## What This Skill Does
+
+Generates the engineering foundation for an ibgib app. This includes:
+- **Global State**: Wiring `globalThis.ibgib` with the appropriate app-specific sub-objects.
+- **Bootstrap flow**: Handling `DOMContentLoaded` and asynchronously loading the heavy ibgib engine.
+- **Storage**: Initializing IndexedDB spaces.
+- **Types & Helpers**: Providing the basic framework for identity and witness coordination.
+
+This skill is often the first step in creating a new app, or used to "ibgib-ify" an existing project. It does NOT generate the App Witness (the business logic) or the UI Shell; use `ibgib-create-app-witness` and `ibgib-create-shell` for those.
+
+---
+
+## Pre-Requisites (check before running)
+
+1. Confirm the target directory exists or ask where to create files.
+2. Verify that `@ibgib/ts-gib`, `@ibgib/helper-gib`, `@ibgib/core-gib`, and
+   `@ibgib/web-gib` are available in the workspace.
+3. Confirm the project has an `AUTO-GENERATED-version.mts` file, or note that
+   one is needed.
+
+---
+
+## Token Reference
+
+| Token | Example value | How it's computed |
+|---|---|---|
+| `{{APP_HUMAN_NAME}}` | `PulmonIQ Learning` | Asked of developer |
+| `{{APP_NAME_UPPER}}` | `PULMONIQ_LEARNING` | Uppercase + underscores of app name |
+| `{{APP_CLASSNAME_PREFIX}}` | `PulmoniqLearning` | PascalCase, no suffix |
+| `{{APP_DIR_NAME}}` | `pulmoniq-learning` | kebab-case |
+| `{{DB_NAME}}` | `pulmoniq_learning_db` | Asked of developer |
+| `{{STORE_NAME}}` | `pulmoniq_learning_store` | Asked of developer |
+| `{{APP_UUID}}` | `8d6217327e6490650169be9cb22a0b25` | **Generated fresh** with `generate-id.js`. |
+
+---
+
+## Generation Steps
+
+### 1. Confirm token values
+
+Derive tokens from the developer's answers. Generate a fresh `{{APP_UUID}}` using:
+
+```bash
+node .agents/skills/ibgib-add-core-engine/generate-id.js
+```
+
+### 2. Generate all files
+
+Apply token substitutions to templates in `templates/` and write to the target directory (`src/` by default).
+
+| Template file | Output file |
+|---|---|
+| `templates/index.html.template` | `index.html` |
+| `templates/index.mts.template` | `index.mts` |
+| `templates/bootstrap.mts.template` | `bootstrap.mts` |
+| `templates/constants.mts.template` | `constants.mts` |
+| `templates/types.mts.template` | `types.mts` |
+| `templates/helpers.web.mts.template` | `helpers.web.mts` |
+| `templates/style.css.template` | `style.css` (if missing) |
+
+### 3. Replace `genuuid` placeholders
+
+Replace every `(I: genuuid)`, `(W: genuuid)`, etc., with unique IDs from `generate-id.js`.
+
+---
+
+## Reference Implementations
+
+- **Standalone Pattern**: These templates are designed to be self-contained. They import from shared `@ibgib/*` packages and use standard relative paths for app-internal files.
+- **Library Integration (Optional)**: If the project uses a shared framework layer (like a `common` library), manually update imports in the generated files to point to that layer after scaffolding.

package/tools/auto-generated-agent-skills/skills/ibgib-add-core-engine/generate-id.js

@@ -0,0 +1,9 @@
+const crypto = require('crypto');
+
+const yearStr = new Date().getFullYear().toString().slice(-2);
+
+for (let i = 0; i < 10; i++) {
+    const hash = crypto.createHash('md5').update(crypto.randomBytes(16)).digest('hex');
+    const id = hash.slice(0, 30) + yearStr;
+    console.log(id);
+}

package/tools/auto-generated-agent-skills/skills/ibgib-add-core-engine/templates/bootstrap.mts.template

@@ -0,0 +1,58 @@
+/**
+ * @module bootstrap
+ *
+ * Startup code for ibgib-specific things: initializing the metaspace and
+ * starting the {{APP_HUMAN_NAME}} app.
+ *
+ * Called dynamically by index.mts AFTER initial page render, so the heavy
+ * ibgib import graph doesn't block first paint.
+ */
+
+import { bootstrapIbGibApp } from "../../../libs/ibgib-common/dist/bootstrap.mjs";
+
+import { APP_CONFIG, GLOBAL_LOG_A_LOT } from "./constants.mjs";
+import { getIbGibGlobalThis_{{APP_CLASSNAME_PREFIX}} } from "./helpers.web.mjs";
+import { {{APP_CLASSNAME}} } from "./witness/app/{{APP_DIR_NAME}}/{{APP_DIR_NAME}}-app-v1.mjs";
+import { PARAM_INFOS } from "./witness/app/{{APP_DIR_NAME}}/{{APP_DIR_NAME}}-constants.mjs";
+import { DEFAULT_{{APP_NAME_UPPER}}_APP_DATA_V1 } from "./witness/app/{{APP_DIR_NAME}}/{{APP_DIR_NAME}}-types.mjs";
+import { AUTO_GENERATED_VERSION } from "./AUTO-GENERATED-version.mjs";
+import { registerDeprecatedFunctionNamesAndFunctionInfos_Web } from "./api/function-infos.web.mjs";
+
+// {{OPTIONAL_SHELL_IMPORT}}
+// import { get{{APP_CLASSNAME_PREFIX}}ShellSvc } from "./ui/shell/{{APP_DIR_NAME}}-shell-service.mjs";
+
+// {{OPTIONAL_IDENTITY_IMPORT}}
+// import { resolveIdentity } from "./identity/{{APP_DIR_NAME}}-identity.mjs";
+
+console.log(`[{{APP_DIR_NAME}} bootstrap] version: ${AUTO_GENERATED_VERSION}`);
+
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+
+export async function bootstrap{{APP_CLASSNAME_PREFIX}}App() {
+    await bootstrapIbGibApp({
+        config: APP_CONFIG,
+        getGlobalThis: getIbGibGlobalThis_{{APP_CLASSNAME_PREFIX}},
+        AppClass: {{APP_CLASSNAME}},
+        defaultAppData: DEFAULT_{{APP_NAME_UPPER}}_APP_DATA_V1,
+        paramInfos: PARAM_INFOS,
+        registerAgentFunctionInfos: registerDeprecatedFunctionNamesAndFunctionInfos_Web,
+        
+        // {{OPTIONAL_IDENTITY_BLOCK_START}}
+        // resolveIdentity: async (metaspace) => {
+        //     const identity = await resolveIdentity(metaspace);
+        //     window.dispatchEvent(new CustomEvent('ibgib-identity-resolved', {
+        //         detail: { identity }
+        //     }));
+        //     return identity;
+        // },
+        // {{OPTIONAL_IDENTITY_BLOCK_END}}
+
+        onReady: async (app) => {
+            if (GLOBAL_LOG_A_LOT) { console.log(`[bootstrap{{APP_CLASSNAME_PREFIX}}App] Engine ready. app: ${app?.ib}`); }
+            // {{OPTIONAL_SHELL_ONREADY}}
+            // await get{{APP_CLASSNAME_PREFIX}}ShellSvc().onEngineReady();
+        },
+    });
+}

package/tools/auto-generated-agent-skills/skills/ibgib-add-core-engine/templates/constants.mts.template

@@ -0,0 +1,75 @@
+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 "./types.mjs";
+
+// ---------------------------------------------------------------------------
+// Logging / debug
+// ---------------------------------------------------------------------------
+
+export const GLOBAL_LOG_A_LOT = false;
+
+// ---------------------------------------------------------------------------
+// Storage — unique per app instance
+// ---------------------------------------------------------------------------
+
+export const {{APP_NAME_UPPER}}_DB_NAME = '{{DB_NAME}}';
+export const {{APP_NAME_UPPER}}_STORE_NAME = '{{STORE_NAME}}';
+export const {{APP_NAME_UPPER}}_API_KEY_NAME = '{{API_KEY_NAME}}';
+
+export const {{APP_NAME_UPPER}}_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 {{APP_NAME_UPPER}}_INDEXEDDB_LOCAL_SPACE_NAME_PREFIX = '{{SPACE_NAME_PREFIX}}';
+
+// ---------------------------------------------------------------------------
+// App identity discriminator
+//
+// NOTE: This value MUST be unique per app. It is used by
+// isExecutingInBlankGibWebAppProper() to distinguish the top-level shell from
+// embedded iframes. Generate a fresh UUID when creating a new app.
+// ---------------------------------------------------------------------------
+
+export const HTML_META_APP_ID_NAME = "ibgib-app-id";
+export const HTML_META_APP_ID_CONTENT = "{{APP_UUID}}";
+
+// ---------------------------------------------------------------------------
+// Agent / AI
+// ---------------------------------------------------------------------------
+
+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';
+
+// ---------------------------------------------------------------------------
+// Ambient context config — the single config object passed through the app
+// ---------------------------------------------------------------------------
+
+export const APP_CONFIG: IbGibAmbientContextConfig = {
+    dbName: {{APP_NAME_UPPER}}_DB_NAME,
+    storeName: {{APP_NAME_UPPER}}_STORE_NAME,
+    additionalStoreNames: [ZERO_SPACE_ID],
+    apiKeyName: {{APP_NAME_UPPER}}_API_KEY_NAME,
+};

package/tools/auto-generated-agent-skills/skills/ibgib-add-core-engine/templates/declarations.d.ts.template

@@ -0,0 +1,9 @@
+declare module "*.css" {
+  const content: string;
+  export default content;
+}
+
+declare module "*.html" {
+  const content: string;
+  export default content;
+}

package/tools/auto-generated-agent-skills/skills/ibgib-add-core-engine/templates/helpers.web.mts.template

@@ -0,0 +1,199 @@
+/**
+ * @module helpers.web
+ *
+ * Web-specific helper functions. Handles storage initialization, globalThis
+ * wiring, and dynamic script loading.
+ *
+ * NOTE: initIbGibStorage, initIbGibGlobalThis, and dynamicallyLoadBootstrapScript
+ * are candidates for upstreaming into @ibgib/web-gib.
+ */
+
+import { extractErrorMsg } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+import { storageGet } from "@ibgib/web-gib/dist/storage/storage-helpers.web.mjs";
+import { initAppStorage } from "@ibgib/web-gib/dist/helpers.web.mjs";
+import { getGlobalMetaspace_waitIfNeeded } from "@ibgib/web-gib/dist/helpers.mjs";
+import { IbGibDynamicComponentMetaCtorOpts } from "@ibgib/web-gib/dist/ui/component/component-types.mjs";
+import { IbGibGlobalThisInfo } from "@ibgib/web-gib/dist/types.mjs";
+import { delay } from "@ibgib/helper-gib/dist/helpers/utils-helper.mjs";
+
+import { GLOBAL_LOG_A_LOT } from "./constants.mjs";
+import { AUTO_GENERATED_VERSION } from "./AUTO-GENERATED-version.mjs";
+import {
+    IbGibAmbientContextConfig,
+    IbGibGlobalThis_{{APP_CLASSNAME_PREFIX}},
+    IbGibGlobalThis_Common,
+} from "./types.mjs";
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+// ---------------------------------------------------------------------------
+// Storage initialization
+// ---------------------------------------------------------------------------
+
+/**
+ * Initializes the IndexedDB stores required by this app.
+ * Call once on DOMContentLoaded, before bootstrap.
+ */
+export async function initIbGibStorage(config: IbGibAmbientContextConfig): Promise<void> {
+    const lc = `[${initIbGibStorage.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: genuuid)`); }
+        await initAppStorage({
+            infos: [
+                {
+                    dbName: config.dbName,
+                    storeNames: [config.storeName, ...(config.additionalStoreNames ?? [])],
+                },
+            ],
+        });
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// globalThis initialization
+// ---------------------------------------------------------------------------
+
+/**
+ * Sets up globalThis.ibgib.{{APP_GLOBALTHIS_KEY}} once.
+ * Safe to call multiple times (idempotent).
+ */
+export function initIbGibGlobalThis(config: IbGibAmbientContextConfig): void {
+    const lc = `[${initIbGibGlobalThis.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: genuuid)`); }
+
+        if (!(globalThis as any).ibgib) {
+            (globalThis as any).ibgib = {
+                dbName_hack: config.dbName,
+                apiKeyName_hack: config.apiKeyName,
+                storeName_hack: config.storeName,
+            } satisfies IbGibGlobalThisInfo;
+        }
+
+        if (!(globalThis as any).ibgib.{{APP_GLOBALTHIS_KEY}}) {
+            (globalThis as any).ibgib.{{APP_GLOBALTHIS_KEY}} = {
+                version: AUTO_GENERATED_VERSION,
+                spaceShim: {},
+                fnDefaultGetAPIKey: async () => {
+                    const apiKey = await storageGet({
+                        dbName: config.dbName,
+                        storeName: config.storeName,
+                        key: config.apiKeyName,
+                    });
+                    return apiKey ?? '';
+                },
+                dbName_hack: config.dbName,
+                apiKeyName_hack: config.apiKeyName,
+                storeName_hack: config.storeName,
+            } satisfies IbGibGlobalThis_{{APP_CLASSNAME_PREFIX}};
+        }
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// GlobalThis accessors
+// ---------------------------------------------------------------------------
+
+export function getIbGibGlobalThis_{{APP_CLASSNAME_PREFIX}}(
+    config?: IbGibAmbientContextConfig
+): IbGibGlobalThis_{{APP_CLASSNAME_PREFIX}} {
+    if (!(globalThis as any).ibgib?.{{APP_GLOBALTHIS_KEY}}) {
+        if (!config) {
+            throw new Error(`Global context not initialized and config not provided.`);
+        }
+        initIbGibGlobalThis(config);
+    }
+    return (globalThis as any).ibgib.{{APP_GLOBALTHIS_KEY}} as IbGibGlobalThis_{{APP_CLASSNAME_PREFIX}};
+}
+
+export function getIbGibGlobalThis_Common(): IbGibGlobalThis_Common {
+    const g = (globalThis as any).ibgib?.{{APP_GLOBALTHIS_KEY}};
+    if (!g) {
+        throw new Error(`(UNEXPECTED) globalThis.ibgib.{{APP_GLOBALTHIS_KEY}} not initialized.`);
+    }
+    return g as IbGibGlobalThis_Common;
+}
+
+// ---------------------------------------------------------------------------
+// API key helper
+// ---------------------------------------------------------------------------
+
+export function getDefaultFnGetAPIKey(): () => Promise<string> {
+    return async () => {
+        const gb = getIbGibGlobalThis_{{APP_CLASSNAME_PREFIX}}();
+        return (await storageGet({
+            dbName: gb.dbName_hack,
+            storeName: gb.storeName_hack,
+            key: gb.apiKeyName_hack,
+        })) ?? '';
+    };
+}
+
+// ---------------------------------------------------------------------------
+// Dynamic bootstrap loading
+// ---------------------------------------------------------------------------
+
+/**
+ * Dynamically imports the bootstrap module and calls the app's bootstrap
+ * function. Called after DOMContentLoaded so the initial page render is not
+ * blocked by the heavy ibgib import graph.
+ */
+export async function dynamicallyLoadBootstrapScript(path: string): Promise<void> {
+    const lc = `[${dynamicallyLoadBootstrapScript.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: genuuid)`); }
+        const module = await import(path);
+        await module.bootstrap{{APP_CLASSNAME_PREFIX}}App();
+    } catch (error) {
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+// ---------------------------------------------------------------------------
+// Component constructor args helper
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the standard ctor options for IbGib dynamic components, including
+ * a bootstrap promise wrapper so components can await app readiness.
+ */
+export function getComponentCtorArg(): IbGibDynamicComponentMetaCtorOpts {
+    const fnGetMetaspace = async () => getGlobalMetaspace_waitIfNeeded();
+
+    const bootstrapPromiseWrapper = new Promise<void>(async (resolve, reject) => {
+        try {
+            let maxTries = 100_000;
+            let counter = 0;
+            let bootstrapPromise: Promise<void> | undefined;
+            do {
+                bootstrapPromise =
+                    getIbGibGlobalThis_{{APP_CLASSNAME_PREFIX}}()?.bootstrapPromise;
+                counter++;
+                if (counter > maxTries) { break; }
+                await delay(10);
+            } while (bootstrapPromise === undefined);
+            if (!bootstrapPromise) {
+                throw new Error(`Timed out waiting for bootstrapPromise. (E: genuuid)`);
+            }
+            await bootstrapPromise;
+            resolve();
+        } catch (error) {
+            reject(error);
+        }
+    });
+
+    return { fnGetMetaspace, bootstrapPromise: bootstrapPromiseWrapper };
+}

package/tools/auto-generated-agent-skills/skills/ibgib-add-core-engine/templates/index.html.template

@@ -0,0 +1,65 @@
+<!DOCTYPE html>
+<html lang="en-US">
+
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <!--
+    HTML_META_APP_ID: Used by isExecutingInBlankGibWebAppProper() to detect
+    whether code is running in the top-level shell vs. an embedded iframe.
+    The content value MUST be unique per app (generate a fresh UUID at scaffold time).
+  -->
+  <meta name="ibgib-app-id" content="{{APP_UUID}}" />
+  <title>{{APP_HUMAN_NAME}}</title>
+  <link rel="stylesheet" type="text/css" href="style.css">
+  <script type="module" src="index.mjs" defer></script>
+</head>
+
+<body>
+  <!--
+    REQUIRED: fullscreen-dialog
+    This block is required by @ibgib/web-gib helper functions (alertUser,
+    promptForText, promptForSecret, promptForConfirm). Do not remove or rename
+    the element IDs prefixed with "fullscreen-dialog-".
+  -->
+  <dialog id="fullscreen-dialog" class="fullscreen-dialog">
+    <div id="fullscreen-dialog-content" class="fullscreen-dialog-content">
+      <div id="fullscreen-dialog-header" class="fullscreen-dialog-header">
+        <h2 id="fullscreen-dialog-title"></h2>
+      </div>
+      <div id="fullscreen-dialog-body" class="fullscreen-dialog-body">
+        <div id="fullscreen-dialog-message" class="fullscreen-dialog-message"></div>
+        <input type="text" id="fullscreen-dialog-prompt-input" class="collapsed">
+      </div>
+      <div id="fullscreen-dialog-footer" class="fullscreen-dialog-footer">
+        <button id="fullscreen-dialog-ok-button" class="dialog-button">OK</button>
+        <button id="fullscreen-dialog-cancel-button" class="dialog-button">Cancel</button>
+      </div>
+    </div>
+  </dialog>
+
+  <!--
+    SHELL: Everything below this line is the consumer's responsibility.
+
+    The ibgib framework does not prescribe any layout. Replace the content of
+    <body> beyond the dialog above with whatever shell your app needs:
+      - HTML panels (see apps/learning or tmp/blank-gib for examples)
+      - A <canvas> element for a game engine frontend
+      - Nothing (if the app has no visual shell — e.g. a background worker)
+
+    The framework calls your onReady() callback (configured in bootstrap.mts)
+    when the metaspace and App witness are initialized. Wire your shell to
+    that callback.
+
+    If your app uses identity, listen for the 'ibgib-identity-resolved' window
+    event to update the shell's auth state.
+  -->
+
+  <div id="app-root">
+    <!-- Replace this placeholder with your actual shell markup -->
+    <p>{{APP_HUMAN_NAME}} shell loading...</p>
+  </div>
+
+</body>
+
+</html>

package/tools/auto-generated-agent-skills/skills/ibgib-add-core-engine/templates/index.mts.template

@@ -0,0 +1,61 @@
+import { extractErrorMsg } from '@ibgib/helper-gib/dist/helpers/utils-helper.mjs';
+
+import { GLOBAL_LOG_A_LOT, APP_CONFIG } from './constants.mjs';
+import {
+    initIbGibStorage,
+    initIbGibGlobalThis,
+    dynamicallyLoadBootstrapScript,
+} from './helpers.web.mjs';
+
+// {{OPTIONAL_ROUTER_IMPORT}}
+// import { simpleIbGibRouterSingleton as router } from './ui/router/router-one-file.mjs';
+
+initIbGibGlobalThis(APP_CONFIG);
+
+const logalot = GLOBAL_LOG_A_LOT;
+
+/**
+ * Initiates startup without blocking DOMContentLoaded.
+ *
+ * Sequence:
+ *   1. Init IndexedDB storage
+ *   2. (Optional) trigger shell / router
+ *   3. Dynamically import bootstrap.mts — the heavy ibgib graph loads here
+ */
+async function spinOffStartup(): Promise<void> {
+    const lc = `[${spinOffStartup.name}]`;
+    try {
+        if (logalot) { console.log(`${lc} starting... (I: genuuid)`); }
+        console.time(lc);
+
+        document.addEventListener('DOMContentLoaded', async () => {
+            try {
+                console.timeLog(lc, 'DOMContentLoaded fired');
+
+                await initIbGibStorage(APP_CONFIG);
+                console.timeLog(lc, 'initIbGibStorage complete');
+
+                // {{OPTIONAL_ROUTER_CALL}}
+                // router.loadCurrentURLPath();
+
+                await dynamicallyLoadBootstrapScript('./bootstrap.mjs');
+                console.timeLog(lc, 'dynamicallyLoadBootstrapScript complete');
+
+                console.timeEnd(lc);
+            } catch (error) {
+                console.error(`${lc} ${extractErrorMsg(error)}`);
+                throw error;
+            }
+        });
+
+    } catch (error) {
+        console.timeEnd(lc);
+        debugger; // error in index.mts — investigate immediately
+        console.error(`${lc} ${extractErrorMsg(error)}`);
+        throw error;
+    } finally {
+        if (logalot) { console.log(`${lc} complete.`); }
+    }
+}
+
+spinOffStartup();