@zhin.js/plugin-runtime 1.1.17 → 1.1.18

package/lib/snapshot.js

@@ -11,18 +11,20 @@ export class GenerationConflictError extends Error {
 }
 const snapshotLeaseAuthority = Symbol('SnapshotLeaseAuthority');
 export class SnapshotLease {
+    #released = false;
     value;
     releaseRecord;
-    retirementSignal;
-    #released = false;
-    constructor(value, releaseRecord, authority, 
     /** Aborted on publication of a replacement or Root close, before lease disposal. */
-    retirementSignal) {
-        this.value = value;
-        this.releaseRecord = releaseRecord;
-        this.retirementSignal = retirementSignal;
+    retirementSignal;
+    /** Root closure only; shared by leases from every generation and never aborted by HMR. */
+    stopSignal;
+    constructor(input, authority) {
         if (authority !== snapshotLeaseAuthority)
             throw new TypeError('SnapshotLease is owned by SnapshotStore');
+        this.value = input.value;
+        this.releaseRecord = input.releaseRecord;
+        this.retirementSignal = input.retirementSignal;
+        this.stopSignal = input.stopSignal;
     }
     get active() {
         return !this.#released;
@@ -38,11 +40,14 @@ export class SnapshotStore {
     onDisposalError;
     #current;
     #retired = new Set();
-    #leases = new WeakSet();
+    #leases = new WeakMap();
+    #rootResource;
     #closed = false;
+    #stop = new AbortController();
     constructor(initial, onDisposalError = () => undefined, ...state) {
         this.onDisposalError = onDisposalError;
         const initialState = state[0];
+        this.#rootResource = state[1];
         const snapshot = createSnapshotView(0, initial);
         const committed = Object.freeze({ snapshot, state: initialState });
         const admissions = collectSnapshotAdmissions(snapshot);
@@ -57,7 +62,8 @@ export class SnapshotStore {
             retired: false,
         };
         this.#current = record;
-        replaceGenerationAdmissions(new Set(), admissions, this, () => undefined, () => this.#retain(record));
+        replaceGenerationAdmissions({ previous: new Set(), next: admissions, owner: this,
+            publishNext: () => undefined, acquireNext: () => this.#retain(record), stopSignal: this.#stop.signal });
     }
     get current() {
         return this.#current.snapshot;
@@ -69,14 +75,43 @@ export class SnapshotStore {
     acquire() {
         if (this.#closed)
             throw new Error('SnapshotStore is closed');
-        const record = this.#current;
-        const lease = new SnapshotLease(record.snapshot, this.#retain(record), snapshotLeaseAuthority, record.retirement.signal);
-        this.#leases.add(lease);
+        return this.#lease(this.#current);
+    }
+    retain(lease) {
+        if (this.#closed)
+            throw new Error('SnapshotStore is closed');
+        const record = this.#leases.get(lease);
+        if (!record || !lease.active)
+            throw new Error('Snapshot retention requires an active owned lease');
+        return this.#lease(record);
+    }
+    #lease(record) {
+        const releaseRecord = this.#retain(record);
+        const lease = new SnapshotLease({
+            value: record.snapshot,
+            releaseRecord: () => {
+                this.#leases.set(lease, null);
+                releaseRecord();
+            },
+            retirementSignal: record.retirement.signal,
+            stopSignal: this.#stop.signal,
+        }, snapshotLeaseAuthority);
+        this.#leases.set(lease, record);
         return lease;
     }
     owns(lease) {
         return this.#leases.has(lease);
     }
+    rootResource(lease, token) {
+        const record = this.#leases.get(lease);
+        if (!record || !lease.active)
+            throw new Error('Root resource access requires an active owned SnapshotLease');
+        // Manually authored snapshots retain their explicit resource contract. Real
+        // Runtime Roots inject the same-generation Scope resolver, including privacy checks.
+        return (this.#rootResource
+            ? this.#rootResource(record.state, record.snapshot.root, token)
+            : record.snapshot.resources.get(record.snapshot.root)?.get(token.id));
+    }
     commit(expectedGeneration, prepared) {
         // The caller owns a candidate until this method succeeds. This lets the
         // transaction authority undo handoff state before disposing a rejection.
@@ -101,7 +136,8 @@ export class SnapshotStore {
             leases: 0,
             retired: false,
         };
-        replaceGenerationAdmissions(previous.admissions, admissions, this, () => { this.#current = next; }, () => this.#retain(next));
+        replaceGenerationAdmissions({ previous: previous.admissions, next: admissions, owner: this,
+            publishNext: () => { this.#current = next; }, acquireNext: () => this.#retain(next), stopSignal: this.#stop.signal });
         // Commit only swaps the active pointer. The previous record may still be
         // serving in-flight work, so disposal is deferred to its final lease.
         previous.retired = true;
@@ -114,7 +150,10 @@ export class SnapshotStore {
         if (this.#closed)
             return;
         this.#closed = true;
-        replaceGenerationAdmissions(this.#current.admissions, new Set(), this, () => undefined);
+        replaceGenerationAdmissions({ previous: this.#current.admissions, next: new Set(), owner: this,
+            publishNext: () => undefined, stopSignal: this.#stop.signal });
+        // Stop observers may synchronously release transports; no gate may admit fresh work then.
+        this.#stop.abort();
         this.#current.retired = true;
         this.#current.retirement.abort();
         this.#retired.add(this.#current);
@@ -226,3 +265,10 @@ class ReadonlyMapView {
 function readonlyMap(values) {
     return new ReadonlyMapView(values);
 }
+/** Compatibility for Host embedders that implement the original minimal SnapshotReader. */
+export function readLeasedRootResource(reader, lease, token) {
+    if (!reader.owns(lease) || !lease.active)
+        throw new Error('Root resource access requires an active owned SnapshotLease');
+    return reader.rootResource ? reader.rootResource(lease, token)
+        : lease.value.resources.get(lease.value.root)?.get(token.id);
+}

package/lib/token.d.ts

@@ -1,5 +1,5 @@
 import { DisposeStack, type Dispose } from './dispose.js';
-import { type PluginId, type TokenId } from './identity.js';
+import { type FeatureId, type PluginId, type TokenId } from './identity.js';
 export interface Token<T> {
     readonly id: TokenId;
     readonly description?: string;
@@ -7,6 +7,10 @@ export interface Token<T> {
 }
 export declare function createToken<T>(id: string, description?: string): Token<T>;
 export declare function createRootPrivateToken<T>(id: string, description?: string): Token<T>;
+/** A Root-private capability readable only while projecting its owning Feature. */
+export declare function createFeaturePrivateToken<T>(id: string, feature: FeatureId, description?: string): Token<T>;
+/** @internal The actual candidate Root Scope never enters the Feature context. */
+export declare function readFeaturePrivateResource<T>(scope: Pick<Scope, 'has' | 'use'>, feature: FeatureId, token: Token<T>): T | undefined;
 /** @internal Ends a facade's candidate declarations on seal or failed setup disposal. */
 export declare const scopeSetupFinalizer: unique symbol;
 export declare class Scope {

package/lib/token.js

@@ -1,6 +1,7 @@
 import { DisposeStack } from './dispose.js';
 import { tokenId } from './identity.js';
 const rootPrivateTokens = new WeakSet();
+const featurePrivateTokens = new WeakMap();
 export function createToken(id, description) {
     return Object.freeze({ id: tokenId(id), description });
 }
@@ -9,6 +10,18 @@ export function createRootPrivateToken(id, description) {
     rootPrivateTokens.add(token);
     return Object.freeze(token);
 }
+/** A Root-private capability readable only while projecting its owning Feature. */
+export function createFeaturePrivateToken(id, feature, description) {
+    const token = createRootPrivateToken(id, description);
+    featurePrivateTokens.set(token, feature);
+    return token;
+}
+/** @internal The actual candidate Root Scope never enters the Feature context. */
+export function readFeaturePrivateResource(scope, feature, token) {
+    if (featurePrivateTokens.get(token) !== feature)
+        throw new Error(`Feature cannot access Root resource ${token.id}`);
+    return scope.has(token) ? scope.use(token) : undefined;
+}
 /** @internal Ends a facade's candidate declarations on seal or failed setup disposal. */
 export const scopeSetupFinalizer = Symbol('ScopeSetupFinalizer');
 export class Scope {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/plugin-runtime",
-  "version": "1.1.17",
+  "version": "1.1.18",
   "description": "Zero-dependency Plugin tree, Scope and atomic generation runtime for Zhin",
   "type": "module",
   "main": "./lib/index.js",