@mak-98/dirvi-app 0.11.0-beta.5 → 0.11.0-beta.7

package/dist/application/create-app-api.d.ts

@@ -1,4 +1,4 @@
-import { type SerializableKey, type AppApi } from 'dirvi-lib';
+import { SerializableKey, AppApi } from 'dirvi-lib';
 import type { AppApiApplicator, AppDefinition, AppDefinitionApplicator } from 'dirvi-apis';
 /**
  * Turns a plugin-owned app definition into a host-owned runtime AppApi.

package/dist/application/create-app-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-app-api.d.ts","sourceRoot":"","sources":["../../src/application/create-app-api.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,eAAe,EACpB,KAAK,MAAM,EAMZ,MAAM,WAAW,CAAC;AACnB,OAAO,KAAK,EAAE,gBAAgB,EAAkB,aAAa,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE3G;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,uBAAuB,EAAE,uBAAuB,GAC/C,gBAAgB,CAQlB;AAED,wBAAgB,YAAY,CAC1B,EAAE,SAAS,eAAe,EAC1B,KAAK,EACL,aAAa,EAAE,aAAa,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,CAyB5D"}
+{"version":3,"file":"create-app-api.d.ts","sourceRoot":"","sources":["../../src/application/create-app-api.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,MAAM,EACP,MAAM,WAAW,CAAC;AAKnB,OAAO,KAAK,EAAE,gBAAgB,EAAkB,aAAa,EAAE,uBAAuB,EAAE,MAAM,YAAY,CAAC;AAE3G;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,uBAAuB,EAAE,uBAAuB,GAC/C,gBAAgB,CAQlB;AAED,wBAAgB,YAAY,CAC1B,EAAE,SAAS,eAAe,EAC1B,KAAK,EACL,aAAa,EAAE,aAAa,CAAC,EAAE,EAAE,KAAK,CAAC,GAAG,MAAM,CAAC,EAAE,EAAE,KAAK,CAAC,CAiE5D"}

package/dist/application/create-app-api.js

@@ -1,4 +1,5 @@
-import { createCursorApi, createFoldsApi, createNavNodeApi, createStateApi, createTreeNodeApi, } from 'dirvi-lib';
+import { createFoldMethods, createCursorMethods, createUnorderedNavMethods, createOrderedNavMethods, } from 'dirvi-lib';
+import { createTreeMethods, createStateApi, } from 'dirvi-lib';
 /**
  * Turns a plugin-owned app definition into a host-owned runtime AppApi.
  *
@@ -12,22 +13,48 @@ export function createAppApiApplicator(appDefinitionApplicator) {
     });
 }
 export function createAppApi(appDefinition) {
-    const treeNodeApi = createTreeNodeApi();
-    const foldTreeNodeApi = createTreeNodeApi();
-    const foldsApi = createFoldsApi(foldTreeNodeApi);
-    const cursorApi = createCursorApi();
-    const stateApi = createStateApi(treeNodeApi, cursorApi);
-    const navNodeApi = createNavNodeApi(treeNodeApi, foldsApi, cursorApi, appDefinition.createNavNodeApiOptions);
+    const treeMethods = createTreeMethods();
+    const foldTreeMethods = createTreeMethods();
+    const foldMethods = createFoldMethods(foldTreeMethods);
+    const cursorMethods = createCursorMethods();
+    const stateApi = createStateApi(treeMethods, foldMethods, cursorMethods);
+    const navMethods = appDefinition.semanticOrder ?
+        createOrderedNavMethods(treeMethods, foldMethods, cursorMethods) :
+        createUnorderedNavMethods(treeMethods, foldMethods, cursorMethods);
+    async function loadChildren(path) {
+        const children = await appDefinition.loadChildren(path);
+        const seenIds = new Set();
+        return children.map((child) => {
+            if (seenIds.has(child.id)) {
+                throw new Error('Application returned duplicate sibling IDs');
+            }
+            seenIds.add(child.id);
+            switch (child.kind) {
+                case 'leaf':
+                    return treeMethods.createLeaf(child.id, child.value);
+                case 'unloaded-branch':
+                    return treeMethods.createUnloadedBranch(child.id, child.value);
+                default:
+                    // Also protects against invalid output from JavaScript plugins.
+                    throw new Error('Application returned an invalid child kind');
+            }
+        });
+    }
     return {
         name: appDefinition.displayName,
-        rootId: appDefinition.rootId,
-        createRoot: () => appDefinition.createRoot(treeNodeApi),
-        loadBranches: (path) => appDefinition.loadChildren(treeNodeApi, path),
+        loadChildren: (path) => loadChildren(path),
+        loadRoot: async () => {
+            const rootData = await appDefinition.loadRoot();
+            const children = await loadChildren([]);
+            const root = treeMethods.createLoadedBranch(rootData.id, rootData.value, children);
+            if (root === undefined) {
+                throw new Error('Cannot create root: duplicate child IDs');
+            }
+            return root;
+        },
+        presentNode: (id, isBranch) => appDefinition.presentNode(id, isBranch),
         subscribeToResync: appDefinition.subscribeToResync,
-        treeNodeApi,
-        foldsApi,
-        cursorApi,
         stateApi,
-        navNodeApi,
+        navMethods,
     };
 }

package/dist/application/init-runtime.d.ts

@@ -1,20 +1,40 @@
 import type { Initialization } from '../domain/initialization.js';
 import type { PublicInitApi } from '../domain/public-init-api.js';
 /**
- * Collects startup configuration registrations while init.mjs is evaluated.
+ * A session for collecting and resolving initialization-script registrations.
  *
- * The application exposes `api` to the script, then calls `finish()` once
- * evaluation completes to seal registration and obtain the validated Config.
+ * Expose `api` while evaluating `init.mjs`, then call `finish()` after module
+ * evaluation completes. Finishing validates the collected state and returns an
+ * immutable-by-contract snapshot of the resolved initialization.
  */
 export type InitRuntime = {
+    /** The temporary API made available to `init.mjs` during evaluation. */
     readonly api: PublicInitApi;
+    /**
+     * Validates and seals this session, returning its resolved startup state.
+     *
+     * The session is sealed only after successful validation. Once sealed,
+     * further API calls and calls to `finish()` throw
+     * `InitializationAlreadyFinishedError`.
+     */
     readonly finish: () => Initialization;
 };
 /**
- * Creates a fresh startup configuration session.
+ * Creates an isolated session for evaluating one `init.mjs` script.
  *
- * Each runtime owns its own mutable configuration while registration is open.
- * The mutable state is not exposed directly to the config script.
+ * Option patches are merged with the current config and the complete result is
+ * validated. App and command registrations are checked as they are made.
+ *
+ * The runtime keeps its working state inside the closure and exposes it only
+ * through `api` and `finish`. finish() returns new maps, so later changes to
+ * the runtime’s maps cannot alter the returned maps.
+ *
+ * If no startup app is selected explicitly, the most recently registered app
+ * is chosen. At least one app must be registered before the session can finish.
+ *
+ * @returns A fresh initialization API and its corresponding `finish` function.
+ * @throws {InitRuntimeError} If a registration is invalid, validation fails,
+ *   no app was registered, or the session has already been finished.
  */
 export declare function createInitRuntime(): InitRuntime;
 //# sourceMappingURL=init-runtime.d.ts.map

package/dist/application/init-runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init-runtime.d.ts","sourceRoot":"","sources":["../../src/application/init-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAElE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAIlE;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,cAAc,CAAC;CACvC,CAAC;AAEF;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,WAAW,CAiI/C"}
+{"version":3,"file":"init-runtime.d.ts","sourceRoot":"","sources":["../../src/application/init-runtime.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAElE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAWlE;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,wEAAwE;IACxE,QAAQ,CAAC,GAAG,EAAE,aAAa,CAAC;IAE5B;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,cAAc,CAAC;CACvC,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,iBAAiB,IAAI,WAAW,CAuI/C"}

package/dist/application/init-runtime.error.d.ts

@@ -0,0 +1,53 @@
+/** Stable categories for errors raised while collecting startup initialization. */
+export type InitRuntimeErrorCode = 'ALREADY_FINISHED' | 'INVALID_VALUE' | 'DUPLICATE_APP' | 'DUPLICATE_EX_COMMAND' | 'INVALID_EX_COMMAND_HANDLER' | 'INVALID_CONFIG' | 'INVALID_APP_PACKAGE_REFERENCE' | 'NO_APPS_REGISTERED' | 'INITIAL_APP_NOT_REGISTERED' | 'INTERNAL_INVARIANT';
+/**
+ * Base class for errors raised by the initialization runtime.
+ *
+ * Consumers can use `code` for reliable error handling without depending on
+ * message text. `cause` is set when an underlying validation error is wrapped.
+ */
+export declare class InitRuntimeError extends Error {
+    readonly code: InitRuntimeErrorCode;
+    constructor(code: InitRuntimeErrorCode, message: string, options?: ErrorOptions);
+}
+/** An initialization API was used after its runtime had been sealed. */
+export declare class InitializationAlreadyFinishedError extends InitRuntimeError {
+    constructor();
+}
+/** A registration API received a value of the wrong type or an empty string. */
+export declare class InvalidInitializationValueError extends InitRuntimeError {
+    constructor(label: string, expected: string);
+}
+/** An app ID was registered more than once. */
+export declare class DuplicateAppRegistrationError extends InitRuntimeError {
+    constructor(id: string);
+}
+/** An Ex command name was registered more than once. */
+export declare class DuplicateExCommandRegistrationError extends InitRuntimeError {
+    constructor(name: string);
+}
+/** An Ex command registration supplied a value that is not a handler function. */
+export declare class InvalidExCommandHandlerError extends InitRuntimeError {
+    constructor();
+}
+/** The initialization script supplied options that do not resolve to valid config. */
+export declare class InvalidInitializationConfigError extends InitRuntimeError {
+    constructor(cause: unknown);
+}
+/** An app registration supplied a package reference that failed validation. */
+export declare class InvalidAppPackageReferenceError extends InitRuntimeError {
+    constructor(cause: unknown);
+}
+/** Initialization completed without registering any apps. */
+export declare class NoAppsRegisteredError extends InitRuntimeError {
+    constructor();
+}
+/** The explicitly selected startup app was not registered. */
+export declare class InitialAppNotRegisteredError extends InitRuntimeError {
+    constructor(id: string);
+}
+/** An internal invariant required by the initialization runtime was violated. */
+export declare class InitRuntimeInvariantError extends InitRuntimeError {
+    constructor(message: string);
+}
+//# sourceMappingURL=init-runtime.error.d.ts.map

package/dist/application/init-runtime.error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"init-runtime.error.d.ts","sourceRoot":"","sources":["../../src/application/init-runtime.error.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,MAAM,MAAM,oBAAoB,GAC5B,kBAAkB,GAClB,eAAe,GACf,eAAe,GACf,sBAAsB,GACtB,4BAA4B,GAC5B,gBAAgB,GAChB,+BAA+B,GAC/B,oBAAoB,GACpB,4BAA4B,GAC5B,oBAAoB,CAAC;AAEzB;;;;;GAKG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IAEvC,QAAQ,CAAC,IAAI,EAAE,oBAAoB;gBAA1B,IAAI,EAAE,oBAAoB,EACnC,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE,YAAY;CAKzB;AAED,wEAAwE;AACxE,qBAAa,kCAAmC,SAAQ,gBAAgB;;CAOvE;AAED,gFAAgF;AAChF,qBAAa,+BAAgC,SAAQ,gBAAgB;gBACvD,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM;CAG5C;AAED,+CAA+C;AAC/C,qBAAa,6BAA8B,SAAQ,gBAAgB;gBACrD,EAAE,EAAE,MAAM;CAMvB;AAED,wDAAwD;AACxD,qBAAa,mCAAoC,SAAQ,gBAAgB;gBAC3D,IAAI,EAAE,MAAM;CAMzB;AAED,kFAAkF;AAClF,qBAAa,4BAA6B,SAAQ,gBAAgB;;CAOjE;AAED,sFAAsF;AACtF,qBAAa,gCAAiC,SAAQ,gBAAgB;gBACxD,KAAK,EAAE,OAAO;CAO3B;AAED,+EAA+E;AAC/E,qBAAa,+BAAgC,SAAQ,gBAAgB;gBACvD,KAAK,EAAE,OAAO;CAO3B;AAED,6DAA6D;AAC7D,qBAAa,qBAAsB,SAAQ,gBAAgB;;CAO1D;AAED,8DAA8D;AAC9D,qBAAa,4BAA6B,SAAQ,gBAAgB;gBACpD,EAAE,EAAE,MAAM;CAMvB;AAED,iFAAiF;AACjF,qBAAa,yBAA0B,SAAQ,gBAAgB;gBACjD,OAAO,EAAE,MAAM;CAG5B"}

package/dist/application/init-runtime.error.js

@@ -0,0 +1,77 @@
+/**
+ * Base class for errors raised by the initialization runtime.
+ *
+ * Consumers can use `code` for reliable error handling without depending on
+ * message text. `cause` is set when an underlying validation error is wrapped.
+ */
+export class InitRuntimeError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = new.target.name;
+    }
+}
+/** An initialization API was used after its runtime had been sealed. */
+export class InitializationAlreadyFinishedError extends InitRuntimeError {
+    constructor() {
+        super('ALREADY_FINISHED', 'Initialization has finished. Make all registrations while init.mjs is evaluated.');
+    }
+}
+/** A registration API received a value of the wrong type or an empty string. */
+export class InvalidInitializationValueError extends InitRuntimeError {
+    constructor(label, expected) {
+        super('INVALID_VALUE', `${label} ${expected}.`);
+    }
+}
+/** An app ID was registered more than once. */
+export class DuplicateAppRegistrationError extends InitRuntimeError {
+    constructor(id) {
+        super('DUPLICATE_APP', `An app with ID "${id}" was registered multiple times.`);
+    }
+}
+/** An Ex command name was registered more than once. */
+export class DuplicateExCommandRegistrationError extends InitRuntimeError {
+    constructor(name) {
+        super('DUPLICATE_EX_COMMAND', `An Ex command named "${name}" was registered multiple times.`);
+    }
+}
+/** An Ex command registration supplied a value that is not a handler function. */
+export class InvalidExCommandHandlerError extends InitRuntimeError {
+    constructor() {
+        super('INVALID_EX_COMMAND_HANDLER', 'Ex command handler must be a function.');
+    }
+}
+/** The initialization script supplied options that do not resolve to valid config. */
+export class InvalidInitializationConfigError extends InitRuntimeError {
+    constructor(cause) {
+        super('INVALID_CONFIG', `Initialization produced invalid configuration: ${getErrorMessage(cause)}`, { cause });
+    }
+}
+/** An app registration supplied a package reference that failed validation. */
+export class InvalidAppPackageReferenceError extends InitRuntimeError {
+    constructor(cause) {
+        super('INVALID_APP_PACKAGE_REFERENCE', `Invalid app package reference: ${getErrorMessage(cause)}`, { cause });
+    }
+}
+/** Initialization completed without registering any apps. */
+export class NoAppsRegisteredError extends InitRuntimeError {
+    constructor() {
+        super('NO_APPS_REGISTERED', 'Initialization did not register any apps. Call dirvi.app.register(id, appReference) at least once in init.mjs.');
+    }
+}
+/** The explicitly selected startup app was not registered. */
+export class InitialAppNotRegisteredError extends InitRuntimeError {
+    constructor(id) {
+        super('INITIAL_APP_NOT_REGISTERED', `Startup app "${id}" has not been registered.`);
+    }
+}
+/** An internal invariant required by the initialization runtime was violated. */
+export class InitRuntimeInvariantError extends InitRuntimeError {
+    constructor(message) {
+        super('INTERNAL_INVARIANT', message);
+    }
+}
+function getErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/application/init-runtime.js

@@ -1,117 +1,151 @@
 import { ConfigSchema, defaultConfig, merge } from '../domain/config.js';
+import { AppPackageReference } from '../domain/app-pack-ref.js';
+import { DuplicateAppRegistrationError, DuplicateExCommandRegistrationError, InitializationAlreadyFinishedError, InitRuntimeInvariantError, InvalidAppPackageReferenceError, InvalidExCommandHandlerError, InvalidInitializationConfigError, InvalidInitializationValueError, } from './init-runtime.error.js';
 /**
- * Creates a fresh startup configuration session.
+ * Creates an isolated session for evaluating one `init.mjs` script.
  *
- * Each runtime owns its own mutable configuration while registration is open.
- * The mutable state is not exposed directly to the config script.
+ * Option patches are merged with the current config and the complete result is
+ * validated. App and command registrations are checked as they are made.
+ *
+ * The runtime keeps its working state inside the closure and exposes it only
+ * through `api` and `finish`. finish() returns new maps, so later changes to
+ * the runtime’s maps cannot alter the returned maps.
+ *
+ * If no startup app is selected explicitly, the most recently registered app
+ * is chosen. At least one app must be registered before the session can finish.
+ *
+ * @returns A fresh initialization API and its corresponding `finish` function.
+ * @throws {InitRuntimeError} If a registration is invalid, validation fails,
+ *   no app was registered, or the session has already been finished.
  */
 export function createInitRuntime() {
     let config = defaultConfig;
     let initialAppId;
-    const apps = new Map();
+    const registeredApps = new Map();
     const exCommands = new Map();
     let finished = false;
-    return {
-        api: {
-            options: {
-                set: (patch) => {
-                    // init.mjs is a startup script. It must not modify startup options
-                    // after the host has finished evaluating and consuming it.
-                    if (finished) {
-                        throw new Error('Initialization has finished. Configure dirvi while init.mjs is being evaluated.');
-                    }
-                    // Validate the complete result, not merely the patch. This preserves
-                    // domain invariants even when a patch changes nested configuration.
+    // === Error Helpers =========================================================
+    /**
+     * Rejects API use after a successful call to `finish()`.
+     *
+     * Failed calls to `finish()` do not seal the runtime, allowing the caller to
+     * correct registrations and try again.
+     */
+    const ensureUnfinished = () => {
+        if (finished) {
+            throw new InitializationAlreadyFinishedError();
+        }
+    };
+    /** Validates values. */
+    const validateNonEmptyString = (value, label) => {
+        if (typeof value !== 'string') {
+            throw new InvalidInitializationValueError(label, 'must be a string');
+        }
+        if (value.trim().length === 0) {
+            throw new InvalidInitializationValueError(label, 'must not be empty');
+        }
+    };
+    // === Public Initialization API =============================================
+    const api = {
+        options: {
+            set: (patch) => {
+                ensureUnfinished();
+                try {
+                    // Validate the merged result so patches cannot break config
+                    // invariants outside the fields they directly update.
                     config = ConfigSchema.parse(merge(config, patch));
-                },
+                }
+                catch (cause) {
+                    throw new InvalidInitializationConfigError(cause);
+                }
             },
-            apps: {
-                register: (id, appReference) => {
-                    if (finished) {
-                        throw new Error('Initialization has finished. Register apps while ' +
-                            'init.mjs is being evaluated.');
-                    }
-                    if (id.trim().length === 0) {
-                        throw new Error('App ID must not be empty.');
-                    }
-                    if (apps.has(id)) {
-                        throw new Error(`An app with ID "${id}" was registered multiple times.`);
-                    }
-                    apps.set(id, appReference);
-                },
-                initialAppId: (appId) => {
-                    if (finished) {
-                        throw new Error('Initialization has finished. Select an initial app while ' +
-                            'init.mjs is being evaluated.');
-                    }
-                    if (appId.trim().length === 0) {
-                        throw new Error('App ID must not be empty.');
-                    }
-                    initialAppId = appId;
-                },
+        },
+        app: {
+            register: (id, appReference) => {
+                ensureUnfinished();
+                validateNonEmptyString(id, 'App ID');
+                if (registeredApps.has(id)) {
+                    throw new DuplicateAppRegistrationError(id);
+                }
+                try {
+                    registeredApps.set(id, AppPackageReference.parse(appReference));
+                }
+                catch (cause) {
+                    throw new InvalidAppPackageReferenceError(cause);
+                }
             },
-            ex: {
-                register: (name, execute) => {
-                    if (finished) {
-                        throw new Error('Initialization has finished. Register Ex commands while ' +
-                            'init.mjs is being evaluated.');
-                    }
-                    if (name.trim().length === 0) {
-                        throw new Error('Ex command name must not be empty.');
-                    }
-                    if (exCommands.has(name)) {
-                        throw new Error(`An Ex command named "${name}" was registered multiple times.`);
-                    }
-                    exCommands.set(name, {
-                        name,
-                        execute,
-                    });
-                },
+            initial: (appId) => {
+                ensureUnfinished();
+                validateNonEmptyString(appId, 'App ID');
+                initialAppId = appId;
             },
         },
-        finish: () => {
-            if (finished) {
-                throw new Error('Initialization has already finished.');
-            }
-            if (apps.size === 0) {
-                throw new Error('Initialization did not register any apps. Call ' +
-                    'dirvi.apps.register(id, appReference) at least once in init.mjs.');
-            }
-            if (initialAppId !== undefined) {
-                if (!apps.has(initialAppId)) {
-                    throw new Error(`Startup app "${initialAppId}" has not been registered.`);
+        ex: {
+            register: (name, execute) => {
+                ensureUnfinished();
+                validateNonEmptyString(name, 'Ex command name');
+                if (typeof execute !== 'function') {
+                    throw new InvalidExCommandHandlerError();
                 }
-                finished = true;
-                return {
-                    config,
-                    initialAppId: initialAppId,
-                    registeredApps: new Map(apps),
-                    exCommands: [...exCommands.values()],
-                };
-            }
-            const lastRegisteredAppRef = getLastRegisteredAppId(apps);
-            finished = true;
-            return {
-                config,
-                initialAppId: lastRegisteredAppRef,
-                registeredApps: new Map(apps),
-                exCommands: [...exCommands.values()],
-            };
+                if (exCommands.has(name)) {
+                    throw new DuplicateExCommandRegistrationError(name);
+                }
+                exCommands.set(name, { name, execute });
+            },
         },
     };
+    /**
+     * === FINISH ================================================================
+     * Resolves the startup app, seals the session, and returns its snapshot.
+     *
+     * Validation happens before sealing, so a failed finish can be retried after
+     * the script corrects its registrations.
+     * ===========================================================================
+     */
+    const finish = () => {
+        ensureUnfinished();
+        if (registeredApps.size === 0) {
+            throw new Error('Initialization did not register any apps. Call ' +
+                'dirvi.apps.register(id, appReference) at least once in init.mjs.');
+        }
+        let initial;
+        if (initialAppId !== undefined) {
+            if (!registeredApps.has(initialAppId)) {
+                throw new Error(`Startup app "${initialAppId}" has not been registered.`);
+            }
+            initial = initialAppId;
+        }
+        else {
+            initial = getLastRegisteredAppId(registeredApps);
+        }
+        finished = true;
+        return {
+            config,
+            app: {
+                initial,
+                registered: new Map(registeredApps),
+            },
+            exCommands: new Map(exCommands),
+        };
+    };
+    return {
+        api,
+        finish,
+    };
 }
 /**
- * Returns the most recently registered app ID.
+ * Returns the app registered last, using `Map` insertion order.
+ *
+ * This is only the fallback when `init.mjs` does not explicitly select an
+ * initial app. Callers must check that the map is non-empty first.
  *
- * Map iteration follows registration insertion order. This is a convenience
- * fallback only; init.mjs should set initialAppId explicitly when startup
- * selection is semantically important.
+ * @throws {InitRuntimeInvariantError} If called with an empty map.
  */
 function getLastRegisteredAppId(apps) {
     const appIds = [...apps.keys()];
     const lastAppId = appIds.at(-1);
     if (lastAppId === undefined) {
-        throw new Error('Internal error: Check some app is registered before searching ids.');
+        throw new InitRuntimeInvariantError('Expected at least one registered app when selecting the startup app.');
     }
     return lastAppId;
 }

package/dist/domain/app-input.d.ts

@@ -0,0 +1,2 @@
+export type AppInput = string | undefined;
+//# sourceMappingURL=app-input.d.ts.map

package/dist/domain/app-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-input.d.ts","sourceRoot":"","sources":["../../src/domain/app-input.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC"}

package/dist/domain/app-input.js

@@ -0,0 +1 @@
+export {};

package/dist/domain/ex-command.d.ts

@@ -1,12 +1,15 @@
 import { ShellApi } from './shell-api.js';
+export type DirviApi = {
+    shell: ShellApi;
+};
 /**
  * A command registered by init.mjs and invoked through Ex mode.
  *
- * The command receives the live DirviApi only when it is executed. This keeps
+ * The command receives the live Api only when it is executed. This keeps
  * initialization separate from the running application lifecycle.
  */
 export type ExCommand = {
     readonly name: string;
-    readonly execute: (shell: ShellApi) => void | Promise<void>;
+    readonly execute: (api: DirviApi) => void | Promise<void>;
 };
 //# sourceMappingURL=ex-command.d.ts.map

package/dist/domain/ex-command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ex-command.d.ts","sourceRoot":"","sources":["../../src/domain/ex-command.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7D,CAAC"}
+{"version":3,"file":"ex-command.d.ts","sourceRoot":"","sources":["../../src/domain/ex-command.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C,MAAM,MAAM,QAAQ,GAAG;IACrB,KAAK,EAAE,QAAQ,CAAC;CACjB,CAAA;AAGD;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,QAAQ,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3D,CAAC"}

package/dist/domain/initialization.d.ts

@@ -1,21 +1,24 @@
 import { Config } from './config.js';
 import { ExCommand } from './ex-command.js';
 import { AppPackageReference } from './app-pack-ref.js';
-export type AppInput = string | undefined;
 /**
- * Object set through initialization, i.e. evaluating init.mjs.
+ * Resolved startup state produced by evaluating `init.mjs`.
  *
- * Config is shared tree-UI configuration. App selection is distinct from Config
- * value. Ex commands are executable startup registrations and are therefore
- * stored separately from Config.
- *
- * initialAppId is always the ID of one app in apps: either the app explicitly
- * selected by init.mjs or the most recently registered app.
+ * The initialization script runs before the terminal UI starts. It uses the
+ * temporary `dirvi` configuration facade to set shared options, register app
+ * packages, choose the initial app, and register Ex commands.
  */
 export type Initialization = {
+    /** Dirvi-wide configuration resolved from the initialization script. */
     readonly config: Readonly<Config>;
-    readonly initialAppId: string;
-    readonly registeredApps: ReadonlyMap<string, AppPackageReference>;
-    readonly exCommands: readonly ExCommand[];
+    /** Registered apps and the app selected for startup. */
+    readonly app: {
+        /** ID of the app to open initially; must be present in `registered`. */
+        initial: string;
+        /** App package references keyed by app ID. */
+        registered: ReadonlyMap<string, AppPackageReference>;
+    };
+    /** Ex commands registered by the initialization script, keyed by name. */
+    readonly exCommands: ReadonlyMap<string, ExCommand>;
 };
 //# sourceMappingURL=initialization.d.ts.map

package/dist/domain/initialization.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"initialization.d.ts","sourceRoot":"","sources":["../../src/domain/initialization.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAExD,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;AAE1C;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,cAAc,EAAE,WAAW,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IAClE,QAAQ,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,CAAC;CAC3C,CAAC"}
+{"version":3,"file":"initialization.d.ts","sourceRoot":"","sources":["../../src/domain/initialization.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAExD;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;IAElC,wDAAwD;IACxD,QAAQ,CAAC,GAAG,EAAE;QACZ,wEAAwE;QACxE,OAAO,EAAE,MAAM,CAAC;QAEhB,8CAA8C;QAC9C,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;KACtD,CAAC;IAEF,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CACrD,CAAC"}

package/dist/domain/node-presentation.d.ts

@@ -0,0 +1,12 @@
+/**
+ * A semantic highlight name, not a concrete terminal color.
+ *
+ * Dot-separated names allow fallback to broader categories:
+ * "filesystem.directory" can fall back to "filesystem".
+ */
+export type HighlightToken = string;
+export type NodePresentation = Readonly<{
+    content: string;
+    highlight: HighlightToken;
+}>;
+//# sourceMappingURL=node-presentation.d.ts.map

package/dist/domain/node-presentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-presentation.d.ts","sourceRoot":"","sources":["../../src/domain/node-presentation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC;AAEpC,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,cAAc,CAAC;CAC3B,CAAC,CAAC"}

package/dist/domain/node-presentation.js

@@ -0,0 +1 @@
+export {};