@ibgib/web-gib 0.0.35 → 0.0.42

package/CHANGELOG.md

@@ -3,13 +3,24 @@
 _note: as you implement features/fixes/etc., please document them here under the "Working Version" section. These will be moved to a concrete version number during the next publish._
 
 ## Working Version
+
+## 0.0.37-42
+* chore: centralized build orchestration
+  * migrated build, clean, and test logic to the root `@ibgib/build-gib` orchestrator.
+  * pruned legacy `package.json` scripts and archived them in `docs/ARCHIVE_SCRIPTS.md`.
+  * updated `prepare:publish` to use the centralized build engine.
+  * documented the new **Monorepo Build Policy** in the README.
 * progress: genai package dep testing chain build
   * the package.json file no longer had a direct ref to @google/genai
     or a dev dependency to node types. I'm trying to troubleshoot this by
     adding back genai to package.json and doing a chain publish from web-gib.
     I want to see if that chain publish is removing deps or if this happened
     previously when we streamlined the monorepo.
+* meta: architecture and agent skill modernization
+  * updated `README.md` to document the new 8-file foundational bootstrap architecture.
+  * modernized `ibgib-create-app-core` and `ibgib-create-shell` agent skills to support the new `script.mts` pattern.
+  * established the three-phase bootstrap standard (`script.mts` -> `index.mts` -> `bootstrap.mts`).
 
-## 0.0.x
+## 0.0.36
 * working on pulling out common app code from blank-gib into this lib
   for use among multiple apps.

package/README.md

@@ -4,6 +4,19 @@
 
 This library enables ibgib apps with...
 
+## Build (Monorepo Policy)
+
+> [!IMPORTANT]
+> This project is part of a monorepo. Build and development tasks are centralized in the monorepo root via the `@ibgib/build-gib` orchestrator.
+
+### Development & Build
+Run these from the monorepo root:
+* `npm run build:web-gib` - Performs a full clean and build.
+* `npm run test:web-gib` - Runs the full respec-gib test suite for this library.
+
+### Legacy Scripts
+Individual package scripts have been streamlined to avoid redundancy. Previous scripts are archived in `docs/ARCHIVE_SCRIPTS.md` at the monorepo root.
+
 * initializing the ibgib environment
   * bootstrapping the metaspace
 * utilizing and interacting with IndexedDB
@@ -64,6 +77,109 @@ Or for the direct script approach:
   }
 ```
 
+## Bootstrapping an IbGib App
+
+`@ibgib/web-gib` provides a streamlined, multi-phase bootstrap process that minimizes boilerplate while maximizing performance. A standard ibgib application consists of **8 foundational files**:
+
+1.  `index.html`: The entry point with script tags for `script.mjs` and `index.mjs`.
+2.  `script.mts`: **Phase 1**. Immediate UI Shell initialization (e.g., burger menus).
+3.  `index.mts`: **Phase 2**. Storage (IndexedDB) and Engine orchestration.
+4.  `bootstrap.mts`: **Phase 3**. The heavy ibgib engine and App witness loading.
+5.  `constants.mts`: App-specific configuration and UUIDs.
+6.  `types.mts`: App-specific global state typing.
+7.  `helpers.web.mts`: Environment-aware initialization utilities.
+8.  `style.css`: Core application styling.
+
+### Phase 1: Immediate Shell Interactivity (`script.mts`)
+
+To ensure the UI is responsive immediately, the Shell is initialized in a dedicated entry point. This script runs as soon as the HTML is parsed.
+
+```typescript
+import { getMyAppShellSvc } from "./ui/shell/my-app-shell-service.mjs";
+
+// Early init of UI Shell logic so the burger menu responds immediately.
+getMyAppShellSvc();
+```
+
+### Phase 2: Environment Orchestration (`index.mts`)
+
+The `index.mts` file handles the asynchronous setup of storage and triggers the dynamic loading of the heavy ibgib engine.
+
+In your app's entry point (`index.mts`), you should initialize the global namespace immediately, then "spin off" the storage and bootstrap loading to avoid blocking the initial DOM paint.
+
+```typescript
+import { 
+    initIbGibStorage, 
+    initIbGibGlobalThis, 
+    dynamicallyLoadBootstrapScript 
+} from '@ibgib/web-gib/dist/app-bootstrap/init-orchestration.mjs';
+
+import { APP_CONFIG } from './constants.mjs';
+import { simpleIbGibRouterSingleton as router } from './ui/router/router-one-file.mjs';
+
+// 1. Initialize global namespace immediately
+initIbGibGlobalThis(APP_CONFIG, 'my_app_key');
+
+/**
+ * spin off to avoid forestalling the DOMContentLoaded from firing
+ */
+async function spinOffStartup(): Promise<void> {
+    document.addEventListener('DOMContentLoaded', async () => {
+        // 2. Prepare storage (IndexedDB)
+        await initIbGibStorage(APP_CONFIG);
+        
+        // 3. Initialize Router
+        router.loadCurrentURLPath();
+
+        // 4. Defer loading the heavy engine
+        await dynamicallyLoadBootstrapScript('./bootstrap.mjs', 'bootstrapMyApp');
+    });
+}
+
+spinOffStartup();
+```
+
+### Phase 2: Dynamic Engine Bootstrap (`bootstrap.mts`)
+
+The `bootstrap.mts` file is loaded dynamically. It handles the initialization of the metaspace, identity, and the application witness using a rich set of lifecycle hooks.
+
+```typescript
+import { bootstrapIbGibApp } from '@ibgib/web-gib/dist/app-bootstrap/bootstrap.mjs';
+import { getIbGibGlobalThis_IbGibApp } from '@ibgib/web-gib/dist/app-bootstrap/init-orchestration.mjs';
+
+import { 
+    APP_CONFIG, 
+    TAG_AGENT_TEXT, TAG_AGENT_ICON, TAG_AGENT_DESCRIPTION,
+    MY_APP_SPACE_PREFIX
+} from './constants.mjs';
+import { MyAppApp_V1 } from './witness/app/my-app-app-v1.mjs';
+import { PARAM_INFOS } from './witness/app/my-app-constants.mjs';
+import { DEFAULT_MY_APP_DATA_V1 } from './witness/app/my-app-types.mjs';
+import { registerAgentFunctionInfos } from './api/function-infos.web.mjs';
+
+export async function bootstrapMyApp() {
+    await bootstrapIbGibApp({
+        config: APP_CONFIG,
+        // Bridge function that provides the typed globalThis for your app
+        getGlobalThis: (config) => getIbGibGlobalThis_IbGibApp('my_app_key', config),
+        AppClass: MyAppApp_V1,
+        defaultAppData: DEFAULT_MY_APP_DATA_V1,
+        paramInfos: PARAM_INFOS,
+        // Lifecycle hooks
+        registerAgentFunctionInfos,
+        ensureTags: [
+            { text: TAG_AGENT_TEXT, icon: TAG_AGENT_ICON, description: TAG_AGENT_DESCRIPTION }
+        ],
+        localSpaceNamePrefix: MY_APP_SPACE_PREFIX,
+        onReady: async (app) => {
+            console.log('Engine ready!');
+            // Initialize your UI shell service here
+            // getAppShellSvc().onEngineReady();
+        }
+    });
+}
+```
+
 ## UI Architecture: Custom @ibgib component framework
 
 **tl;dr**: _Web Component-based components react to ibgib's unique Merkle DAG DLT time-centric data model._

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

@@ -10,5 +10,5 @@
 /**
  * this is the version of this package, auto-updated in the build process
  */
-export declare const AUTO_GENERATED_VERSION = "0.0.35";
+export declare const AUTO_GENERATED_VERSION = "0.0.42";
 //# sourceMappingURL=AUTO-GENERATED-version.d.mts.map

package/dist/AUTO-GENERATED-version.mjs

@@ -10,5 +10,5 @@
 /**
  * this is the version of this package, auto-updated in the build process
  */
-export const AUTO_GENERATED_VERSION = '0.0.35';
+export const AUTO_GENERATED_VERSION = '0.0.42';
 //# sourceMappingURL=AUTO-GENERATED-version.mjs.map

package/dist/app-bootstrap/types.d.mts

@@ -97,6 +97,21 @@ export interface IbGibIdentityContext {
      */
     data?: Record<string, any>;
 }
+/**
+ * Minimal interface for an application's UI Shell.
+ *
+ * ## design notes
+ *
+ * This is intentionally minimal to avoid coupling the bootstrap engine to a
+ * specific UI design (header, panels, etc.).
+ */
+export interface IbGibAppShell {
+    /**
+     * Hook called by the bootstrap engine when the ibGib engine and metaspace
+     * are fully initialized and ready for interaction.
+     */
+    onEngineReady(): void;
+}
 /**
  * Layer 1: Fields shared across ALL ibgib web apps.
  *
@@ -133,6 +148,11 @@ export interface IbGibGlobalThis_Common extends IbGibGlobalThisInfo {
 export interface IbGibGlobalThis_IbGibApp extends IbGibGlobalThis_Common {
     /** Semver string generated at build time. */
     version?: string;
+    /**
+     * The application's UI Shell service.
+     * Initialized by the consumer and registered on the globalThis.
+     */
+    shell?: IbGibAppShell;
     /** Per-space RCLI pathing shim. */
     spaceShim: {
         [spaceId: string]: SpaceShimGlobalInfo;

package/dist/app-bootstrap/types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.mts","sourceRoot":"","sources":["../../src/app-bootstrap/types.mts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,MAAM,uDAAuD,CAAC;AACvF,OAAO,EAAE,WAAW,EAAE,MAAM,4CAA4C,CAAC;AAEzE,OAAO,EAAE,cAAc,EAAE,MAAM,2DAA2D,CAAC;AAC3F,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAMnD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,yBAAyB;IACtC,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;CACtB;AAMD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAChC;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,GAAG,EAAE,MAAM,CAAC;CACf;AAMD,0CAA0C;AAC1C,MAAM,WAAW,qBAAsB,SAAQ,cAAc;IACzD,8CAA8C;IAC9C,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,kCAAkC;IAClC,mBAAmB,EAAE,WAAW,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,uBAAwB,SAAQ,cAAc;CAAI;AAEnE;;;;GAIG;AACH,MAAM,WAAW,sBACb,SAAQ,QAAQ,CAAC,qBAAqB,EAAE,uBAAuB,CAAC;IAChE,iEAAiE;IACjE,MAAM,EAAE,OAAO,CAAC;CACnB;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,oBAAoB;IACjC,gFAAgF;IAChF,QAAQ,EAAE,OAAO,CAAC;IAClB,2DAA2D;IAC3D,aAAa,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC9B;AAMD;;;;;GAKG;AACH,MAAM,WAAW,sBAAuB,SAAQ,mBAAmB;IAC/D;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC;;;OAGG;IACH,oBAAoB,CAAC,EAAE,GAAG,CAAC;CAC9B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,wBAAyB,SAAQ,sBAAsB;IACpE,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,SAAS,EAAE;QAAE,CAAC,OAAO,EAAE,MAAM,GAAG,mBAAmB,CAAA;KAAE,CAAC;IACtD,4DAA4D;IAC5D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,kBAAkB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1C,qEAAqE;IACrE,mBAAmB,CAAC,EAAE,QAAQ,CAAC;IAC/B,kFAAkF;IAClF,wBAAwB,CAAC,EAAE,cAAc,CAAC;IAC1C;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAAC;CAC1C"}
+{"version":3,"file":"types.d.mts","sourceRoot":"","sources":["../../src/app-bootstrap/types.mts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,cAAc,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAC3E,OAAO,EAAE,cAAc,EAAE,MAAM,uDAAuD,CAAC;AACvF,OAAO,EAAE,WAAW,EAAE,MAAM,4CAA4C,CAAC;AAEzE,OAAO,EAAE,cAAc,EAAE,MAAM,2DAA2D,CAAC;AAC3F,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAMnD;;;;;;;;;;GAUG;AACH,MAAM,WAAW,yBAAyB;IACtC,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,kFAAkF;IAClF,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;IAChC,gEAAgE;IAChE,UAAU,EAAE,MAAM,CAAC;CACtB;AAMD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAChC;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,GAAG,EAAE,MAAM,CAAC;CACf;AAMD,0CAA0C;AAC1C,MAAM,WAAW,qBAAsB,SAAQ,cAAc;IACzD,8CAA8C;IAC9C,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,kCAAkC;IAClC,mBAAmB,EAAE,WAAW,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,uBAAwB,SAAQ,cAAc;CAAI;AAEnE;;;;GAIG;AACH,MAAM,WAAW,sBACb,SAAQ,QAAQ,CAAC,qBAAqB,EAAE,uBAAuB,CAAC;IAChE,iEAAiE;IACjE,MAAM,EAAE,OAAO,CAAC;CACnB;AAMD;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,oBAAoB;IACjC,gFAAgF;IAChF,QAAQ,EAAE,OAAO,CAAC;IAClB,2DAA2D;IAC3D,aAAa,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAC9B;AAMD;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC1B;;;OAGG;IACH,aAAa,IAAI,IAAI,CAAC;CACzB;AAMD;;;;;GAKG;AACH,MAAM,WAAW,sBAAuB,SAAQ,mBAAmB;IAC/D;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;OAGG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC;;;OAGG;IACH,oBAAoB,CAAC,EAAE,GAAG,CAAC;CAC9B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,wBAAyB,SAAQ,sBAAsB;IACpE,6CAA6C;IAC7C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,mCAAmC;IACnC,SAAS,EAAE;QAAE,CAAC,OAAO,EAAE,MAAM,GAAG,mBAAmB,CAAA;KAAE,CAAC;IACtD,4DAA4D;IAC5D,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;OAGG;IACH,kBAAkB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1C,qEAAqE;IACrE,mBAAmB,CAAC,EAAE,QAAQ,CAAC;IAC/B,kFAAkF;IAClF,wBAAwB,CAAC,EAAE,cAAc,CAAC;IAC1C;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAAC;CAC1C"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ibgib/web-gib",
-  "version": "0.0.35",
+  "version": "0.0.42",
   "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",
@@ -11,31 +11,10 @@
     "web-gib-init-agents": "./tools/init-agents.js"
   },
   "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",
-    "test": "npm run test:both",
-    "test:both": "npm run build:test && npm run test:node:nobuild && npm run test:browser:nobuild",
-    "man:test:both": "use this if you want to test in both node and browser contexts",
-    "pretest:node": "npm run build:test",
-    "test:node": "node dist/respec-gib.node.mjs --inspect",
-    "man:test:node": "use this if you want to build+test in node",
-    "test:node:nobuild": "node dist/respec-gib.node.mjs --inspect",
-    "man:test:node:nobuild": "use this if you want to test in node but its already built",
-    "test:browser": "npm run build:test && echo \"not implemented yet\"",
-    "man:test:browser": "use this if you want to build+test only the browser context",
-    "test:browser:nobuild": "echo \"not implemented yet\"",
-    "man:test:browser:nobuild": "use this if you want to test only the browser context but its already built",
-    "test:browser:serve": "npm run build:test && echo \"not implemented yet\"",
-    "man:test:browser:serve": "use this if you want to build+test in the browser and don't want the browser to close when your done. (i.e. you're debugging)",
-    "test:browser:serve:nobuild": "\"not implemented yet\"",
-    "man:test:browser:serve:nobuild": "use this if you are troubleshooting existing dist output and don't want to overwrite those files. (and you're debugging in the browser)",
+    "//_orchestration": "~~ ORCHESTRATION (handled by @ibgib/build-gib) ~~",
+    "//_publish": "~~ PUBLISH ~~",
     "pack": "npm pack --pack-destination=\"./published\"",
-    "prepare:publish": "npm run clean && npm version patch && npm run build && npm run pack",
+    "prepare:publish": "npm version patch && node ../../build/dist/concrete-build/build-web-gib.mjs --prod && npm run pack",
     "man:prepare:publish": "use this to patch > build > pack for publishing to npm repo"
   },
   "type": "module",
@@ -49,10 +28,10 @@
   "license": "ISC",
   "dependencies": {
     "@google/genai": "^1.33.0",
-    "@ibgib/core-gib": "^0.1.53",
-    "@ibgib/encrypt-gib": "^0.2.36",
-    "@ibgib/helper-gib": "^0.0.35",
-    "@ibgib/ts-gib": "^0.5.31"
+    "@ibgib/core-gib": "*",
+    "@ibgib/encrypt-gib": "*",
+    "@ibgib/helper-gib": "*",
+    "@ibgib/ts-gib": "*"
   },
   "engines": {
     "node": ">=19.0.0"

package/src/AUTO-GENERATED-version.mts

@@ -11,4 +11,4 @@
 /**
  * this is the version of this package, auto-updated in the build process
  */
-export const AUTO_GENERATED_VERSION = '0.0.35';
+export const AUTO_GENERATED_VERSION = '0.0.42';

package/src/app-bootstrap/types.mts

@@ -122,6 +122,26 @@ export interface IbGibIdentityContext {
     data?: Record<string, any>;
 }
 
+// ---------------------------------------------------------------------------
+// UI Shell
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimal interface for an application's UI Shell.
+ *
+ * ## design notes
+ *
+ * This is intentionally minimal to avoid coupling the bootstrap engine to a
+ * specific UI design (header, panels, etc.).
+ */
+export interface IbGibAppShell {
+    /**
+     * Hook called by the bootstrap engine when the ibGib engine and metaspace
+     * are fully initialized and ready for interaction.
+     */
+    onEngineReady(): void;
+}
+
 // ---------------------------------------------------------------------------
 // GlobalThis layers
 // ---------------------------------------------------------------------------
@@ -163,6 +183,11 @@ export interface IbGibGlobalThis_Common extends IbGibGlobalThisInfo {
 export interface IbGibGlobalThis_IbGibApp extends IbGibGlobalThis_Common {
     /** Semver string generated at build time. */
     version?: string;
+    /** 
+     * The application's UI Shell service. 
+     * Initialized by the consumer and registered on the globalThis.
+     */
+    shell?: IbGibAppShell;
     /** Per-space RCLI pathing shim. */
     spaceShim: { [spaceId: string]: SpaceShimGlobalInfo };
     /** When true, verbose output is enabled for the session. */

package/tools/auto-generated-agent-skills/skills/ibgib-create-app-core/SKILL.md

@@ -2,9 +2,9 @@
 name: ibgib-create-app-core
 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.
+  Generates the 8 foundational files (index.html, index.mts, script.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-create-app-core
@@ -62,13 +62,14 @@ Apply token substitutions to templates in `templates/` and write to the target d
 
 | 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) |
+| templates/index.html.template | `index.html` |
+| templates/index.mts.template | `index.mts` |
+| templates/script.mts.template | `script.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
 

package/tools/auto-generated-agent-skills/skills/ibgib-create-app-core/templates/index.html.template

@@ -12,6 +12,7 @@
   <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="script.mjs" defer></script>
   <script type="module" src="index.mjs" defer></script>
 </head>
 

package/tools/auto-generated-agent-skills/skills/ibgib-create-app-core/templates/script.mts.template

@@ -0,0 +1,17 @@
+/**
+ * script.mts
+ *
+ * Early initialization script for the {{APP_HUMAN_NAME}} app.
+ *
+ * This script is intended to run as soon as the HTML document is parsed,
+ * allowing UI Shell logic (like menus and panels) to be interactive
+ * immediately, without waiting for the heavier ibgib engine bootstrap.
+ */
+
+// import { get{{APP_CLASSNAME_PREFIX}}ShellSvc } from "./ui/shell/{{APP_DIR_NAME}}-shell-service.mjs";
+
+// Early init of UI Shell logic so the burger menu responds immediately.
+// Modules execute after the HTML document has been parsed, so elements are ready.
+// get{{APP_CLASSNAME_PREFIX}}ShellSvc();
+
+console.log('{{APP_HUMAN_NAME}} early script executing...');

package/tools/auto-generated-agent-skills/skills/ibgib-create-shell/SKILL.md

@@ -24,11 +24,17 @@ The skill will generate:
 1. `src/ui/shell/{{APP_DIR_NAME}}-shell-service.mts`
 2. `src/ui/shell/{{APP_DIR_NAME}}-shell-constants.mts`
 3. `src/ui/shell/{{APP_DIR_NAME}}-shell-types.mts`
+4. `src/script.mts`
 
 ## Usage Instructions
 1. Ensure the `src/ui/shell` directory exists or the tool will create it.
-2. Generate the three files from templates.
-3. Update `src/bootstrap.mts` to import and call `get{{APP_CLASSNAME_PREFIX}}ShellSvc().onEngineReady()` in the `execFromArgs` function.
+2. Generate the shell service, constants, and types from templates.
+3. Update `src/script.mts` to import and call the shell factory:
+   ```typescript
+   import { get{{APP_CLASSNAME_PREFIX}}ShellSvc } from "./ui/shell/{{APP_DIR_NAME}}-shell-service.mjs";
+   get{{APP_CLASSNAME_PREFIX}}ShellSvc();
+   ```
+4. Update `src/bootstrap.mts` to import and call `get{{APP_CLASSNAME_PREFIX}}ShellSvc().onEngineReady()` in the `execFromArgs` function.
 
 ## Integration Note
 The shell service provides an `onEngineReady()` hook. This is where you should put logic to "activate" the UI once the ibgib metaspace and app witness are fully initialized.

package/.vscode/ibgib-snippets.code-snippets

@@ -1,309 +0,0 @@
-{
-	// Place your ionic-gib workspace snippets here. Each snippet is defined under a snippet name and has a scope, prefix, body and
-	// description. Add comma separated ids of the languages where the snippet is applicable in the scope field. If scope
-	// is left empty or omitted, the snippet gets applied to all languages. The prefix is what is
-	// used to trigger the snippet and the body will be expanded and inserted. Possible variables are:
-	// $1, $2 for tab stops, $0 for the final cursor position, and ${1:label}, ${2:another} for placeholders.
-	// Placeholders with the same ids are connected.
-	// Example:
-	// "Print to console": {
-	//     "scope": "javascript,typescript",
-	//     "prefix": "log",
-	//     "body": [
-	//         "console.log('$1');",
-	//         "$2"
-	//     ],
-	//     "description": "Log output to console"
-	// }
-	"this Fn lc try..catch rethrow": {
-		"scope": "javascript,typescript",
-		"prefix": "lc_trycatch_rethrow_this",
-		"body": [
-			"const lc = `\\${this.lc}[\\${this.$1.name}]`;",
-			"try {",
-			"\t$SELECTION$0",
-			"} catch (error) {",
-			"\tconsole.error(`\\${lc} \\${extractErrorMsg(error)}`);",
-			"\tthrow error;",
-			"}"
-		],
-	},
-	"this Fn lc try..catch..finally rethrow": {
-		"scope": "javascript,typescript",
-		"prefix": "lc_trycatchfinally_rethrow_this",
-		"body": [
-			"const lc = `\\${this.lc}[\\${this.$1.name}]`;",
-			"try {",
-			"\t$SELECTION$0",
-			"} catch (error) {",
-			"\tconsole.error(`\\${lc} \\${extractErrorMsg(error)}`);",
-			"\tthrow error;",
-			"} finally {",
-			"\t$2",
-			"}"
-		],
-	},
-	"this Fn lc try..catch..finally rethrow with logging": {
-		"scope": "javascript,typescript",
-		"prefix": "lc_trycatchfinally_rethrow_withlogging_this",
-		"body": [
-			"const lc = `\\${this.lc}[\\${this.$1.name}]`;",
-			"try {",
-			"\tif (logalot) { console.log(`\\${lc} starting... (I: $RANDOM_HEX$RANDOM_HEX$RANDOM_HEX$RANDOM_HEX$RANDOM_HEX$CURRENT_YEAR_SHORT)`); }",
-			"\t$SELECTION$0",
-			"} catch (error) {",
-			"\tconsole.error(`\\${lc} \\${extractErrorMsg(error)}`);",
-			"\tthrow error;",
-			"} finally {",
-			"\tif (logalot) { console.log(`\\${lc} complete.`); }",
-			"}"
-		],
-	},
-	"this Fn func async lc try..catch rethrow": {
-		"scope": "javascript,typescript",
-		"prefix": "this_func_lc_trycatch_rethrow_this",
-		"body": [
-			"${1:async function} ${2:fnName}({",
-			"\t$3,",
-			"}: {",
-			"\t$3: $4,",
-			"}): Promise<$5> {",
-			"\tconst lc = `\\${this.lc}[\\${this.$2.name}]`;",
-			"\ttry {",
-			"\t\t$SELECTION$0",
-			"\t} catch (error) {",
-			"\t\tconsole.error(`\\${lc} \\${extractErrorMsg(error)}`);",
-			"\t\tthrow error;",
-			"\t}",
-			"}"
-		],
-	},
-	"this Fn func async lc try..catch..finally rethrow": {
-		"scope": "javascript,typescript",
-		"prefix": "this_func_lc_trycatchfinally_rethrow_this",
-		"body": [
-			"${1:async function} ${2:fnName}({",
-			"\t$3,",
-			"}: {",
-			"\t$3: $4,",
-			"}): Promise<$5> {",
-			"\tconst lc = `\\${this.lc}[\\${this.$2.name}]`;",
-			"\ttry {",
-			"\t\t$SELECTION$0",
-			"\t} catch (error) {",
-			"\t\tconsole.error(`\\${lc} \\${extractErrorMsg(error)}`);",
-			"\t\tthrow error;",
-			"\t} finally {",
-			"\t\t$6",
-			"\t}",
-			"}"
-		],
-	},
-	"this Fn func async lc try..catch..finally rethrow with logging": {
-		"scope": "javascript,typescript",
-		"prefix": "this_func_lc_trycatchfinally_rethrow_withlogging_this",
-		"body": [
-			"${1:async function} ${2:fnName}({",
-			"\t$3,",
-			"}: {",
-			"\t$3: $4,",
-			"}): Promise<$5> {",
-			"\tconst lc = `\\${this.lc}[\\${this.$2.name}]`;",
-			"\ttry {",
-			"\t\tif (logalot) { console.log(`\\${lc} starting... (I: $RANDOM_HEX$RANDOM_HEX$RANDOM_HEX$RANDOM_HEX$RANDOM_HEX$CURRENT_YEAR_SHORT)`); }",
-			"\t\t$SELECTION$0",
-			"\t} catch (error) {",
-			"\t\tconsole.error(`\\${lc} \\${extractErrorMsg(error)}`);",
-			"\t\tthrow error;",
-			"\t} finally {",
-			"\t\tif (logalot) { console.log(`\\${lc} complete.`); }",
-			"\t}",
-			"}"
-		],
-	},
-	"Fn lc try..catch rethrow": {
-		"scope": "javascript,typescript",
-		"prefix": "lc_trycatch_rethrow",
-		"body": [
-			"const lc = `[\\${$1.name}]`;",
-			"try {",
-			"\t$SELECTION$0",
-			"} catch (error) {",
-			"\tconsole.error(`\\${lc} \\${extractErrorMsg(error)}`);",
-			"\tthrow error;",
-			"}"
-		],
-	},
-	"Fn lc try..catch..finally rethrow": {
-		"scope": "javascript,typescript",
-		"prefix": "lc_trycatchfinally_rethrow",
-		"body": [
-			"const lc = `[\\${$1.name}]`;",
-			"try {",
-			"\t$SELECTION$0",
-			"} catch (error) {",
-			"\tconsole.error(`\\${lc} \\${extractErrorMsg(error)}`);",
-			"\tthrow error;",
-			"} finally {",
-			"\t$2",
-			"}"
-		],
-	},
-	"Fn lc try..catch..finally rethrow with logging": {
-		"scope": "javascript,typescript",
-		"prefix": "lc_trycatchfinally_rethrow_withlogging",
-		"body": [
-			"const lc = `[\\${$1.name}]`;",
-			"try {",
-			"\tif (logalot) { console.log(`\\${lc} starting... (I: $RANDOM_HEX$RANDOM_HEX$RANDOM_HEX$RANDOM_HEX$RANDOM_HEX$CURRENT_YEAR_SHORT)`); }",
-			"\t$SELECTION$0",
-			"} catch (error) {",
-			"\tconsole.error(`\\${lc} \\${extractErrorMsg(error)}`);",
-			"\tthrow error;",
-			"} finally {",
-			"\tif (logalot) { console.log(`\\${lc} complete.`); }",
-			"}"
-		],
-	},
-	"Fn func async lc try..catch rethrow": {
-		"scope": "javascript,typescript",
-		"prefix": "func_lc_trycatch_rethrow",
-		"body": [
-			"${1:export async function} ${2:fnName}({",
-			"\t$3,",
-			"}: {",
-			"\t$3: $4,",
-			"}): Promise<$5> {",
-			"\tconst lc = `[\\${$2.name}]`;",
-			"\ttry {",
-			"\t\t$SELECTION$0",
-			"\t} catch (error) {",
-			"\t\tconsole.error(`\\${lc} \\${extractErrorMsg(error)}`);",
-			"\t\tthrow error;",
-			"\t}",
-			"}"
-		],
-	},
-	"Fn func async lc try..catch..finally rethrow": {
-		"scope": "javascript,typescript",
-		"prefix": "func_lc_trycatchfinally_rethrow",
-		"body": [
-			"${1:export async function} ${2:fnName}({",
-			"\t$3,",
-			"}: {",
-			"\t$3: $4,",
-			"}): Promise<$5> {",
-			"\tconst lc = `[\\${$2.name}]`;",
-			"\ttry {",
-			"\t\t$SELECTION$0",
-			"\t} catch (error) {",
-			"\t\tconsole.error(`\\${lc} \\${extractErrorMsg(error)}`);",
-			"\t\tthrow error;",
-			"\t} finally {",
-			"\t\t$6",
-			"\t}",
-			"}"
-		],
-	},
-	"Fn func async lc try..catch..finally rethrow with logging": {
-		"scope": "javascript,typescript",
-		"prefix": "func_lc_trycatchfinally_rethrow_withlogging",
-		"body": [
-			"${1:export async function} ${2:fnName}({",
-			"\t$3,",
-			"}: {",
-			"\t$3: $4,",
-			"}): Promise<$5> {",
-			"\tconst lc = `[\\${$2.name}]`;",
-			"\ttry {",
-			"\t\tif (logalot) { console.log(`\\${lc} starting... (I: $RANDOM_HEX$RANDOM_HEX$RANDOM_HEX$RANDOM_HEX$RANDOM_HEX$CURRENT_YEAR_SHORT)`); }",
-			"\t\t$SELECTION$0",
-			"\t} catch (error) {",
-			"\t\tconsole.error(`\\${lc} \\${extractErrorMsg(error)}`);",
-			"\t\tthrow error;",
-			"\t} finally {",
-			"\t\tif (logalot) { console.log(`\\${lc} complete.`); }",
-			"\t}",
-			"}"
-		],
-	},
-	"throw new error with guid": {
-		"scope": "javascript,typescript",
-		"prefix": "throw_new_error_with_guid",
-		"body": [
-			"$0throw new Error(`$1 (E: $RANDOM_HEX$RANDOM_HEX$RANDOM_HEX$RANDOM_HEX$RANDOM_HEX$CURRENT_YEAR_SHORT)`); "
-		],
-	},
-	"throw new error with guid (UNEXPECTED)": {
-		"scope": "javascript,typescript",
-		"prefix": "throw_new_error_with_guid_unexpected",
-		"body": [
-			"$0throw new Error(`(UNEXPECTED) $1? (E: $RANDOM_HEX$RANDOM_HEX$RANDOM_HEX$RANDOM_HEX$RANDOM_HEX$CURRENT_YEAR_SHORT)`); "
-		],
-	},
-	"throw new error with guid not implemented": {
-		"scope": "javascript,typescript",
-		"prefix": "throw_new_error_with_guid_not_impl",
-		"body": [
-			"$0throw new Error(`not implemented (E: $RANDOM_HEX$RANDOM_HEX$RANDOM_HEX$RANDOM_HEX$RANDOM_HEX$CURRENT_YEAR_SHORT)`); "
-		],
-	},
-	"if..throw with guid": {
-		"scope": "javascript,typescript",
-		"prefix": "if_throw_with_guid",
-		"body": [
-			"$0if ($1) { throw new Error(`$2 (E: $RANDOM_HEX$RANDOM_HEX$RANDOM_HEX$RANDOM_HEX$RANDOM_HEX$CURRENT_YEAR_SHORT)`); }"
-		],
-	},
-	"if logalot log": {
-		"scope": "javascript,typescript",
-		"prefix": "if_logalot_log",
-		"body": [
-			"$0if (logalot$1) { console.${2:log}(`\\${lc} $3 (I: $RANDOM_HEX$RANDOM_HEX$RANDOM_HEX$RANDOM_HEX$RANDOM_HEX$CURRENT_YEAR_SHORT)`); }"
-		],
-	},
-	"surround log if logalot log": {
-		"scope": "javascript,typescript",
-		"prefix": "surround_log_if_logalot",
-		"body": [
-			"if (logalot) { $SELECTION }"
-		],
-	},
-	"surround if logalot timer console time-timeEnd": {
-		"scope": "javascript,typescript",
-		"prefix": "surround_if_logalot_timer_console_time_timeend",
-		"body": [
-			"let timerName: string;",
-			"const timerEnabled = true",
-			"if (logalot && timerEnabled) {",
-			"\ttimerName = lc.substring(0, ${1:24}) + '[timer $RANDOM_HEX]';",
-			"\tconsole.log(`\\${timerName} starting... (I: $RANDOM_HEX$RANDOM_HEX$RANDOM_HEX$RANDOM_HEX$RANDOM_HEX$CURRENT_YEAR_SHORT)`);",
-			"\tconsole.time(timerName);",
-			"}",
-			"// can intersperse with calls to console.timeLog for intermediate times",
-			"// if (logalot) { console.timeLog(timerName); }",
-			"",
-			"$0$SELECTION",
-			"",
-			"if (logalot && timerEnabled) {",
-			"\tconsole.timeEnd(timerName);",
-			"\tconsole.log(`\\${timerName} complete.`);",
-			"}",
-		],
-	},
-	"if logalot global ibgib timer": {
-		"scope": "javascript,typescript",
-		"prefix": "if_logalot_ibgib_timer",
-		"body": [
-			"if (logalot) { console.log(`\\${lc}\\${c.GLOBAL_TIMER_NAME}`); console.timeLog(c.GLOBAL_TIMER_NAME); }$0"
-		],
-	},
-	"return early": {
-		"scope": "javascript,typescript",
-		"prefix": "return_early",
-		"description": "I like to indicate returning early in a function in a comment, so it's more obvious in the editor if I'm scanning for comments.",
-		"body": [
-			"return$1; /* <<<< returns early */$0",
-		],
-	},
-}

package/.vscode/launch.json

@@ -1,25 +0,0 @@
-{
-    // Use IntelliSense to learn about possible attributes.
-    // Hover to view descriptions of existing attributes.
-    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
-    "version": "0.2.0",
-    "configurations": [
-        {
-            "type": "node",
-            "request": "launch",
-            "name": "npm debug",
-            "runtimeExecutable": "npm",
-            "runtimeArgs": [
-                "run",
-                "debug",
-            ],
-            "port": 9229,
-            "sourceMaps": true,
-            "skipFiles": [
-                "<node_internals>/**"
-            ]
-        },
-
-    ]
-}filename
-filename

package/.vscode/settings.json

@@ -1,68 +0,0 @@
-{
-    "typescript.tsdk": "node_modules/typescript/lib",
-    "search.exclude": {
-        "**/*.BAK": true,
-        "**/*.bak": true,
-        "**/dist": true
-    },
-    "files.watcherExclude": {
-        "**/*.BAK": true,
-        "**/*.bak": true
-    },
-    "editor.formatOnSave": true,
-    "files.insertFinalNewline": true,
-    "files.trimTrailingWhitespace": true,
-    "files.trimFinalNewlines": true,
-    "workbench.colorTheme": "Kimbie Dark",
-    "workbench.colorCustomizations": {
-        "editor.background": "#3e033e",
-        "sideBar.background": "#3e0333",
-        "editor.lineHighlightBackground": "#00ffb718",
-        "activityBar.activeBackground": "#cc3636",
-        "activityBar.background": "#cc3636",
-        "activityBar.foreground": "#e7e7e7",
-        "activityBar.inactiveForeground": "#e7e7e799",
-        "activityBarBadge.background": "#134c13",
-        "activityBarBadge.foreground": "#e7e7e7",
-        "commandCenter.border": "#e7e7e799",
-        "sash.hoverBorder": "#cc3636",
-        "statusBar.background": "#a52a2a",
-        "statusBar.foreground": "#e7e7e7",
-        "statusBarItem.hoverBackground": "#cc3636",
-        "statusBarItem.remoteBackground": "#a52a2a",
-        "statusBarItem.remoteForeground": "#e7e7e7",
-        "titleBar.activeBackground": "#a52a2a",
-        "titleBar.activeForeground": "#e7e7e7",
-        "titleBar.inactiveBackground": "#a52a2a99",
-        "titleBar.inactiveForeground": "#e7e7e799"
-    },
-    "editor.tokenColorCustomizations": {
-        "[Kimbie Dark]": {
-            "variables": "#3e8a17",
-            "comments": "#598cdf8c",
-            "textMateRules": [
-                {
-                    "name": "Lists",
-                    "scope": "markup.list",
-                    "settings": {
-                        "foreground": "#cb76d6"
-                    }
-                },
-                {
-                    "scope": "entity.name.tag",
-                    "settings": {
-                        "foreground": "#6cb548"
-                    }
-                },
-                {
-                    "scope": "string",
-                    "settings": {
-                        "foreground": "#84cad3"
-                    }
-                }
-            ],
-        }
-    },
-    "peacock.color": "brown",
-    "insertGuid.pasteAutomatically": "{n}",
-}

package/.vscode/tasks.json

@@ -1,38 +0,0 @@
-{
-    // See https://go.microsoft.com/fwlink/?LinkId=733558
-    // for the documentation about the tasks.json format
-    "version": "2.0.0",
-    "tasks": [
-        {
-            "type": "npm",
-            "script": "build",
-            "group": "build",
-            "problemMatcher": []
-        },
-        {
-            "type": "npm",
-            "script": "test",
-            "group": "build",
-            "problemMatcher": []
-        },
-        {
-            "type": "npm",
-            "script": "clean",
-            "group": "build",
-            "problemMatcher": []
-        },
-        {
-            "type": "npm",
-            "script": "build:test",
-            "group": "build",
-            "problemMatcher": []
-        },
-        {
-            "type": "npm",
-            "script": "prepare:publish",
-            "group": "build",
-            "problemMatcher": []
-        }
-    ],
-}filename
-filename