nervur 0.21.3 → 0.21.4

package/dist/browser/index.d.ts

@@ -29,6 +29,7 @@ export declare class BrowserTerrain extends PointerTerrain {
     #private;
     readonly where: string;
     constructor(parts?: BrowserParts);
+    get foreground(): boolean;
     claim(): Promise<void>;
     release(): Promise<void>;
 }

package/dist/browser/index.js

@@ -156,6 +156,14 @@ export class BrowserTerrain extends PointerTerrain {
         super({ entropy, loader: new HeldLoader(parts.modules ?? []), custody: new IdbCustody(where, entropy), memory: new IdbMemory(where), faculties: [webFaculty(), webPush], opens: [WEB_OPENING] });
         this.where = where;
     }
+    // A shared or a service worker outlives any one tab, and a service
+    // worker is woken for a push with none open. Anywhere else, a page or a
+    // worker a tab made, the harbor lives with that tab.
+    get foreground() {
+        const scope = globalThis;
+        const is = (name) => typeof scope[name] === 'function' && globalThis instanceof scope[name];
+        return !is('SharedWorkerGlobalScope') && !is('ServiceWorkerGlobalScope');
+    }
     async claim() {
         const locks = globalThis.navigator?.locks;
         if (!locks)

package/dist/contract/index.d.ts

@@ -34,6 +34,7 @@ export type Loaded = Module & {
 };
 export declare abstract class Loader {
     abstract load(from: string): Promise<Loaded | null>;
+    missing(_from: string): string | null;
 }
 export declare abstract class Carrier {
     abstract carry(pk: string, bytes: Uint8Array): Promise<Uint8Array | null>;

package/dist/contract/index.js

@@ -22,6 +22,11 @@ export class Custody {
 // crosses a door and never lives in a cell, so it is the
 // one thing beside the seed a terrain hands in: a map, an import, a bundle.
 export class Loader {
+    // Why a name it found nothing under holds nothing, where it can say more
+    // than that: a bundle names that code comes from it alone.
+    missing(_from) {
+        return null;
+    }
 }
 // Bytes to a ward pk in; bytes, or null for nothing, out. A harbor hands a
 // terrain's carrier what it holds no route for; what it routes goes to its

package/dist/harbor/catalogue.d.ts

@@ -8,6 +8,7 @@ export type ModuleRow = {
 };
 export interface Cataloguing {
     load(from: string): Promise<Loaded | null>;
+    missing(from: string): string | null;
     check(modules: readonly Loaded[]): string | null;
     run(modules: readonly Loaded[]): string | null;
     stands(kinds: readonly string[]): boolean;

package/dist/harbor/catalogue.js

@@ -46,7 +46,7 @@ export class Catalogue extends Faculty {
             const refused = loaded instanceof Error
                 ? loaded.message
                 : loaded === null
-                    ? `not found at ${row.from}`
+                    ? (this.#harbor.missing(row.from) ?? `not found at ${row.from}`)
                     : loaded.module !== module
                         ? `${row.from} is module ${loaded.module}`
                         : this.#harbor.check([...this.#running.values(), loaded]);
@@ -64,7 +64,7 @@ export class Catalogue extends Faculty {
         if (loaded instanceof Error)
             return { error: loaded.message };
         if (loaded === null)
-            return { error: 'no such module' };
+            return { error: this.#harbor.missing(args.from) ?? 'no such module' };
         const running = new Map(this.#running);
         running.set(loaded.module, loaded);
         const refused = this.#harbor.run([...running.values()]);

package/dist/harbor/dock.d.ts

@@ -7,6 +7,7 @@ export interface Hosting {
     route(pk: string, at: readonly string[] | null): boolean;
     keep(): Promise<boolean>;
     failures(): Failures;
+    readonly foreground: boolean;
     sweep(): Promise<string[]>;
     grounds(kind: string): boolean;
     awaken(key: string): Promise<void>;

package/dist/harbor/dock.js

@@ -54,11 +54,16 @@ export class Dock extends WardBeing {
         super(stance);
         this.#hosting = hosting;
     }
-    // The census adds what did not stand, for whoever pilots.
+    // The census adds what did not stand, for whoever pilots, and whether
+    // the harbor lives only as long as a screen.
     describe(asker) {
         const blueprint = super.describe(asker);
-        if (pilots(asker, this.notes(asker)))
-            blueprint.notes.failed = this.#hosting.failures();
+        if (!pilots(asker, this.notes(asker)))
+            return blueprint;
+        const notes = blueprint.notes;
+        notes.failed = this.#hosting.failures();
+        if (this.#hosting.foreground)
+            notes.foreground = true;
         return blueprint;
     }
     get hosted() {

package/dist/harbor/harbor.d.ts

@@ -15,6 +15,7 @@ export declare class Harbor extends Carrier implements Hosting, Cataloguing, Res
     sweep(): Promise<string[]>;
     move(name: string, seed: string, from: string | undefined, to: string | undefined): Promise<string | null>;
     release(name: string, store: string | undefined): Promise<void>;
+    get foreground(): boolean;
     failures(): Failures;
     get box(): Ward;
     get dock(): Dock;
@@ -28,6 +29,7 @@ export declare class Harbor extends Carrier implements Hosting, Cataloguing, Res
     carry(pk: string, bytes: Uint8Array): Promise<Uint8Array | null>;
     classOf(kind: string): BeingClass | undefined;
     load(from: string): Promise<Loaded | null>;
+    missing(from: string): string | null;
     check(modules: readonly Loaded[]): string | null;
     run(modules: readonly Loaded[]): string | null;
     stands(kinds: readonly string[]): boolean;

package/dist/harbor/harbor.js

@@ -153,6 +153,9 @@ export class Harbor extends Carrier {
             return being instanceof Store ? [[key, being]] : [];
         });
     }
+    get foreground() {
+        return this.terrain.foreground;
+    }
     // Hosting: what did not stand when the harbor opened, each alone.
     failures() {
         return { wards: { ...this.#failed.wards }, routes: { ...this.#failed.routes } };
@@ -215,6 +218,9 @@ export class Harbor extends Carrier {
     load(from) {
         return this.terrain.loader.load(from);
     }
+    missing(from) {
+        return this.terrain.loader.missing(from);
+    }
     check(modules) {
         return Registry.refusal(this.#kit, modules);
     }

package/dist/harbor/terrain.d.ts

@@ -15,6 +15,7 @@ export declare abstract class Terrain {
     readonly faculties: readonly GroundFaculty[];
     readonly opens: readonly Opening[];
     readonly wakes: boolean;
+    get foreground(): boolean;
     claim(): Promise<void>;
     stand(_harbor: Harbor): Promise<void>;
     release(): Promise<void>;

package/dist/harbor/terrain.js

@@ -6,6 +6,12 @@ export class Terrain {
     // Whether its carriers wake and listen where their cells say. A harbor
     // opened for one ask and closed again dials and hears nothing.
     wakes = true;
+    // Whether the harbor lives only as long as a screen: a tab's, or a worker
+    // one tab owns. It is reached only while that screen is open, and hears
+    // no push, so its census says so.
+    get foreground() {
+        return false;
+    }
     // Before the harbor opens: a terrain whose ground another run holds
     // refuses here. Once it stands: whatever the ground serves beside it.
     // Once its carriers sleep: what that served, gone.

package/dist/pointer/bodies.d.ts

@@ -18,6 +18,7 @@ export declare class HeldLoader extends Loader {
     #private;
     constructor(modules?: readonly Module[]);
     load(from: string): Promise<Loaded | null>;
+    missing(from: string): string;
 }
 export declare class VolatileMemory extends Memory {
     #private;

package/dist/pointer/bodies.js

@@ -28,7 +28,9 @@ export class HeldCustody extends Custody {
         return Promise.resolve(this.#seed.slice());
     }
 }
-// Modules handed to this object, found by the name each declares.
+// Modules handed to this object, found by the name each declares: the
+// bundle a ground with no disk to load from carries, an edge's or a
+// browser's. A path, a package or any other name is no module of it.
 export class HeldLoader extends Loader {
     #modules = new Map();
     constructor(modules = []) {
@@ -40,6 +42,10 @@ export class HeldLoader extends Loader {
         const m = this.#modules.get(from);
         return Promise.resolve(m ? { module: m.module, version: m.version, classes: m.classes, from } : null);
     }
+    missing(from) {
+        const carried = [...this.#modules.keys()];
+        return `${from} is no module this bundle carries${carried.length === 0 ? ', and it carries none' : `: it carries ${carried.join(', ')}`}`;
+    }
 }
 // Entries that live as long as this object, copied in and out, which is
 // what a restart in one process finds.

package/dist/proof/law.js

@@ -194,7 +194,7 @@ export const lawScenes = (t, expect) => [
             expect.same(lost.names, ['w'], 'the rest of the harbor stands');
             expect.same((await census(lost)).beings.echo?.absent, true);
             expect.same(await lost.root('ask', { being: 'catalogue', method: 'modules' }), {
-                answer: { [law.module]: { version: '1', running: null, from: law.module, failed: `not found at ${law.module}` } },
+                answer: { [law.module]: { version: '1', running: null, from: law.module, failed: `${law.module} is no module this bundle carries, and it carries none` } },
             });
             const again = await world.restart('h', { ...t.again(bodies), loader: new HeldLoader([law]) });
             expect.same((await census(again)).beings.echo?.absent, false);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nervur",
-  "version": "0.21.3",
+  "version": "0.21.4",
   "description": "Nervur's kit of Quo: an object asks another object and gets an answer, without knowing where it is.",
   "keywords": [
     "quo",

package/src/browser/index.ts

@@ -175,6 +175,15 @@ export class BrowserTerrain extends PointerTerrain {
     this.where = where;
   }
 
+  // A shared or a service worker outlives any one tab, and a service
+  // worker is woken for a push with none open. Anywhere else, a page or a
+  // worker a tab made, the harbor lives with that tab.
+  override get foreground(): boolean {
+    const scope = globalThis as unknown as Record<string, unknown>;
+    const is = (name: string): boolean => typeof scope[name] === 'function' && globalThis instanceof (scope[name] as new () => unknown);
+    return !is('SharedWorkerGlobalScope') && !is('ServiceWorkerGlobalScope');
+  }
+
   override async claim(): Promise<void> {
     const locks = (globalThis as { navigator?: { locks?: LockManager } }).navigator?.locks;
     if (!locks) return;

package/src/contract/index.ts

@@ -67,6 +67,11 @@ export type Loaded = Module & { readonly from: string };
 // one thing beside the seed a terrain hands in: a map, an import, a bundle.
 export abstract class Loader {
   abstract load(from: string): Promise<Loaded | null>;
+  // Why a name it found nothing under holds nothing, where it can say more
+  // than that: a bundle names that code comes from it alone.
+  missing(_from: string): string | null {
+    return null;
+  }
 }
 
 // Bytes to a ward pk in; bytes, or null for nothing, out. A harbor hands a

package/src/harbor/catalogue.ts

@@ -29,6 +29,8 @@ export type ModuleRow = { version: string; from: string; kinds: string[] };
 // What the catalogue asks of her harbor.
 export interface Cataloguing {
   load(from: string): Promise<Loaded | null>;
+  // Why nothing loads from a name, where the loader says more.
+  missing(from: string): string | null;
   // Why these modules cannot run together, or null.
   check(modules: readonly Loaded[]): string | null;
   // The modules run from now on, or why they cannot be.
@@ -72,7 +74,7 @@ export class Catalogue extends Faculty {
         loaded instanceof Error
           ? loaded.message
           : loaded === null
-            ? `not found at ${row.from}`
+            ? (this.#harbor.missing(row.from) ?? `not found at ${row.from}`)
             : loaded.module !== module
               ? `${row.from} is module ${loaded.module}`
               : this.#harbor.check([...this.#running.values(), loaded]);
@@ -86,7 +88,7 @@ export class Catalogue extends Faculty {
     if (!text(args.from)) return { error: 'from is text' };
     const loaded = await this.#harbor.load(args.from).catch((e: Error) => e);
     if (loaded instanceof Error) return { error: loaded.message };
-    if (loaded === null) return { error: 'no such module' };
+    if (loaded === null) return { error: this.#harbor.missing(args.from) ?? 'no such module' };
     const running = new Map(this.#running);
     running.set(loaded.module, loaded);
     const refused = this.#harbor.run([...running.values()]);

package/src/harbor/dock.ts

@@ -46,6 +46,8 @@ export interface Hosting {
   keep(): Promise<boolean>;
   // What did not stand when the harbor opened.
   failures(): Failures;
+  // Whether the harbor lives only as long as a screen.
+  readonly foreground: boolean;
   // Every place of the memory the dock does not name, gone.
   sweep(): Promise<string[]>;
   // Whether a kind is a carrier this harbor's ground ships.
@@ -92,10 +94,14 @@ export class Dock extends WardBeing implements Lender {
     this.#hosting = hosting;
   }
 
-  // The census adds what did not stand, for whoever pilots.
+  // The census adds what did not stand, for whoever pilots, and whether
+  // the harbor lives only as long as a screen.
   override describe(asker: Asker): Blueprint {
     const blueprint = super.describe(asker);
-    if (pilots(asker, this.notes(asker))) (blueprint.notes as JsonObject).failed = this.#hosting.failures();
+    if (!pilots(asker, this.notes(asker))) return blueprint;
+    const notes = blueprint.notes as JsonObject;
+    notes.failed = this.#hosting.failures();
+    if (this.#hosting.foreground) notes.foreground = true;
     return blueprint;
   }
 

package/src/harbor/harbor.ts

@@ -175,6 +175,10 @@ export class Harbor extends Carrier implements Hosting, Cataloguing, Resolving {
     });
   }
 
+  get foreground(): boolean {
+    return this.terrain.foreground;
+  }
+
   // Hosting: what did not stand when the harbor opened, each alone.
   failures(): Failures {
     return { wards: { ...this.#failed.wards }, routes: { ...this.#failed.routes } };
@@ -246,6 +250,10 @@ export class Harbor extends Carrier implements Hosting, Cataloguing, Resolving {
     return this.terrain.loader.load(from);
   }
 
+  missing(from: string): string | null {
+    return this.terrain.loader.missing(from);
+  }
+
   check(modules: readonly Loaded[]): string | null {
     return Registry.refusal(this.#kit, modules);
   }

package/src/harbor/terrain.ts

@@ -25,6 +25,12 @@ export abstract class Terrain {
   // Whether its carriers wake and listen where their cells say. A harbor
   // opened for one ask and closed again dials and hears nothing.
   readonly wakes: boolean = true;
+  // Whether the harbor lives only as long as a screen: a tab's, or a worker
+  // one tab owns. It is reached only while that screen is open, and hears
+  // no push, so its census says so.
+  get foreground(): boolean {
+    return false;
+  }
 
   // Before the harbor opens: a terrain whose ground another run holds
   // refuses here. Once it stands: whatever the ground serves beside it.

package/src/pointer/bodies.ts

@@ -32,7 +32,9 @@ export class HeldCustody extends Custody {
   }
 }
 
-// Modules handed to this object, found by the name each declares.
+// Modules handed to this object, found by the name each declares: the
+// bundle a ground with no disk to load from carries, an edge's or a
+// browser's. A path, a package or any other name is no module of it.
 export class HeldLoader extends Loader {
   readonly #modules = new Map<string, Module>();
   constructor(modules: readonly Module[] = []) {
@@ -43,6 +45,10 @@ export class HeldLoader extends Loader {
     const m = this.#modules.get(from);
     return Promise.resolve(m ? { module: m.module, version: m.version, classes: m.classes, from } : null);
   }
+  override missing(from: string): string {
+    const carried = [...this.#modules.keys()];
+    return `${from} is no module this bundle carries${carried.length === 0 ? ', and it carries none' : `: it carries ${carried.join(', ')}`}`;
+  }
 }
 
 // Entries that live as long as this object, copied in and out, which is

package/src/proof/law.ts

@@ -203,7 +203,7 @@ export const lawScenes = (t: Terrain, expect: Expect): [string, () => Promise<vo
       expect.same(lost.names, ['w'], 'the rest of the harbor stands');
       expect.same(((await census(lost)) as { beings: Record<string, { absent: boolean }> }).beings.echo?.absent, true);
       expect.same(await lost.root('ask', { being: 'catalogue', method: 'modules' }), {
-        answer: { [law.module]: { version: '1', running: null, from: law.module, failed: `not found at ${law.module}` } },
+        answer: { [law.module]: { version: '1', running: null, from: law.module, failed: `${law.module} is no module this bundle carries, and it carries none` } },
       });
       const again = await world.restart('h', { ...t.again(bodies), loader: new HeldLoader([law]) });
       expect.same(((await census(again)) as { beings: Record<string, { absent: boolean }> }).beings.echo?.absent, false);