@vicin/sigil 1.1.0 → 1.2.0

package/dist/index.d.mts

@@ -304,9 +304,9 @@ interface SigilOptions {
  * predicates implemented by the `Sigilify` mixin.
  *
  * @template L - Narrow string literal type representing the label.
- * @template US - Optinal original Untyped Sigil constructor type being augmented.
+ * @template P - Optinal parent to extend its '__SIGIL_BRAND__'.
  */
-interface ISigilStatic<L extends string = string, US extends Function = never> {
+interface ISigilStatic<L extends string = string, P extends Function = never> {
     /**
      * Compile-time nominal brand that encodes the class label `L` plus parent's brand keys `BrandOf<P>`.
      *
@@ -320,7 +320,7 @@ interface ISigilStatic<L extends string = string, US extends Function = never> {
      */
     readonly __SIGIL_BRAND__: Prettify<{
         [k in L]: true;
-    } & SigilBrandOf<US>>;
+    } & SigilBrandOf<P>>;
     /** Class-level label constant (human readable). */
     readonly SigilLabel: string;
     /** Class-level unique symbol used as the runtime type identifier. */
@@ -379,9 +379,9 @@ interface ISigilStatic<L extends string = string, US extends Function = never> {
  * The methods mirror the instance helpers injected by the mixin.
  *
  * @template L - Narrow string literal type for the label returned by `getSigilLabel`.
- * @template US - Optinal original Untyped Sigil constructor type being augmented.
+ * @template P - Optinal parent to extend its '__SIGIL_BRAND__'.
  */
-interface ISigilInstance<L extends string = string, US extends Function = never> {
+interface ISigilInstance<L extends string = string, P extends Function = never> {
     /**
      * Compile-time nominal brand that encodes the class label `L` plus parent's brand keys `BrandOf<P>`.
      *
@@ -395,7 +395,7 @@ interface ISigilInstance<L extends string = string, US extends Function = never>
      */
     readonly __SIGIL_BRAND__: Prettify<{
         [k in L]: true;
-    } & SigilBrandOf<US>>;
+    } & SigilBrandOf<P>>;
     /** Returns human-readable sigil label of the class constructor. */
     getSigilLabel(): string;
     /** Returns runtime sigil type symbol of the class constructor. */
@@ -413,46 +413,59 @@ interface ISigilInstance<L extends string = string, US extends Function = never>
  * by `Sigilify`.
  *
  * @template L - Narrow string literal type for the label.
- * @template US - Optinal original Untyped Sigil constructor type being augmented.
+ * @template P - Optinal parent to extend its '__SIGIL_BRAND__'.
  */
-type ISigil<L extends string = string, US extends Function = never> = Constructor<ISigilInstance<L, US>> & ISigilStatic<L, US>;
+type ISigil<L extends string = string, P extends Function = never> = Constructor<ISigilInstance<L, P>> & ISigilStatic<L, P>;
 /** -----------------------------------------
- *  Helper sigil types
+ *  HOF pattern types
  * ----------------------------------------- */
-/**
- * Extract the compile-time brand map from a sigil constructor `S`.
- *
- * @typeParam S - A sigil constructor type (e.g. `typeof SomeSigilClass`).
- * @returns The brand record carried on the constructor's instance type (e.g. `{ User: true, Admin: true }`).
- *
- * @remarks
- * - This helper is used purely at the type level to compute the set of brand keys
- *   that should be propagated to derived sigils.
- * - If `S` does not carry a `__SIGIL_BRAND__`, the resulting type is `never` and `IfNever<>`
- *   collapses it to an empty record.
- */
-type SigilBrandOf<S> = IfNever<S extends {
-    readonly __SIGIL_BRAND__: infer Brand;
-} ? Prettify<Brand> : never, Record<string, true>>;
 /**
  * Combine an existing sigil constructor type `S` with a **new** label `L`,
  * while inheriting/propagating compile-time brands from an optional parent sigil `P`.
  *
- * @template US - The original Untyped Sigil constructor type being augmented.
+ * @template S - The original Untyped Sigil constructor type being augmented.
  * @template L - The new label literal to associate with the resulting constructor.
  */
-type TypedSigil<US extends Function, L extends string = string> = US & ISigil<L, US>;
+type TypedSigil<S extends Function, L extends string = string> = S & AppendLabel<L> & Constructor<AppendLabel<L>>;
 /**
  * Generic helper extract instance of the class even in protected and private constructors.
  */
 type GetInstance<T> = T extends {
     prototype: infer R;
-} ? Prettify<R & {
+} ? PrettifyBrand<R & {
     __SIGIL_BRAND__: SigilBrandOf<T>;
 }> : never;
+/** Helper to append label into a class. */
+type AppendLabel<L extends string> = {
+    readonly __SIGIL_BRAND__: Prettify<{
+        [K in L]: true;
+    }>;
+};
+/** -----------------------------------------
+ *  Manual pattern types
+ * ----------------------------------------- */
+/** Update '__SIGIL_BRAND__' field when manual typing is used. */
+type UpdateSigilBrand<L extends string, P extends ISigilInstance> = Prettify<SigilBrandOf<P> & {
+    [K in L]: true;
+}>;
 /** -----------------------------------------
  *  Generic types
  * ----------------------------------------- */
+/**
+ * Extract the compile-time brand map from a sigil constructor `S`.
+ *
+ * @typeParam S - A sigil constructor type (e.g. `typeof SomeSigilClass`).
+ * @returns The brand record carried on the constructor's instance type (e.g. `{ User: true, Admin: true }`).
+ *
+ * @remarks
+ * - This helper is used purely at the type level to compute the set of brand keys
+ *   that should be propagated to derived sigils.
+ * - If `S` does not carry a `__SIGIL_BRAND__`, the resulting type is `never` and `IfNever<>`
+ *   collapses it to an empty record.
+ */
+type SigilBrandOf<S> = IfNever<S extends {
+    readonly __SIGIL_BRAND__: infer Brand;
+} ? Brand : never, Record<string, true>>;
 /**
  * Generic type for class constructors used by the Sigil utilities.
  *
@@ -463,10 +476,14 @@ type GetInstance<T> = T extends {
  * @template P - Parameter tuple type for the constructor.
  */
 type Constructor<T = object, P extends any[] = any[]> = new (...args: P) => T;
-/** Helper type to prettify value. */
+/** Helper type to prettify value */
 type Prettify<T> = {
     [K in keyof T]: T[K];
 } & {};
+/** Helper type to prettify value, handles nested '__SIGIL_BRAND__' field */
+type PrettifyBrand<T> = {
+    [K in keyof T]: K extends '__SIGIL_BRAND__' ? PrettifyBrand<T[K]> : T[K];
+} & {};
 /** Helper type to replace 'never' with another type */
 type IfNever<T, R = {}> = [T] extends [never] ? R : T;
 
@@ -478,13 +495,17 @@ type IfNever<T, R = {}> = [T] extends [never] ? R : T;
  */
 declare const Sigil: {
     new (...args: any[]): {
-        readonly __SIGIL_BRAND__: Record<string, true>;
+        readonly __SIGIL_BRAND__: {
+            Sigil: true;
+        };
         getSigilLabel(): string;
         getSigilType(): symbol;
         getSigilTypeLineage(): readonly symbol[];
         getSigilTypeSet(): Readonly<Set<symbol>>;
     };
-    readonly __SIGIL_BRAND__: Record<string, true>;
+    readonly __SIGIL_BRAND__: {
+        Sigil: true;
+    };
     get SigilLabel(): string;
     get SigilType(): symbol;
     get SigilTypeLineage(): readonly symbol[];
@@ -492,7 +513,10 @@ declare const Sigil: {
     isSigilified(obj: unknown): obj is ISigil;
     isOfType<T extends ISigil>(this: T, other: unknown): other is InstanceType<T>;
     isOfTypeStrict<T extends ISigil>(this: T, other: unknown): other is InstanceType<T>;
+} & {
+    new (): {};
 };
+type Sigil = InstanceType<typeof Sigil>;
 /**
  * A sigil variant of the built-in `Error` constructor used by the library
  * to represent Sigil-specific errors.
@@ -502,13 +526,19 @@ declare const Sigil: {
  */
 declare const SigilError: {
     new (...args: any[]): {
-        readonly __SIGIL_BRAND__: Record<string, true>;
+        readonly __SIGIL_BRAND__: {
+            Sigil: true;
+            SigilError: true;
+        };
         getSigilLabel(): string;
         getSigilType(): symbol;
         getSigilTypeLineage(): readonly symbol[];
         getSigilTypeSet(): Readonly<Set<symbol>>;
     };
-    readonly __SIGIL_BRAND__: Record<string, true>;
+    readonly __SIGIL_BRAND__: {
+        Sigil: true;
+        SigilError: true;
+    };
     get SigilLabel(): string;
     get SigilType(): symbol;
     get SigilTypeLineage(): readonly symbol[];
@@ -516,7 +546,8 @@ declare const SigilError: {
     isSigilified(obj: unknown): obj is ISigil;
     isOfType<T extends ISigil>(this: T, other: unknown): other is InstanceType<T>;
     isOfTypeStrict<T extends ISigil>(this: T, other: unknown): other is InstanceType<T>;
-};
+} & ErrorConstructor;
+type SigilError = InstanceType<typeof SigilError>;
 
 /**
  * Class decorator factory that attaches sigil statics to a class constructor.
@@ -543,7 +574,7 @@ declare const SigilError: {
  * @param opts - Options object to override any global options if needed.
  * @returns A class decorator compatible with the ECMAScript decorator context.
  */
-declare function WithSigil<L extends string>(label?: L, opts?: SigilOptions): (value: Function, context: ClassDecoratorContext) => void;
+declare function WithSigil<L extends string>(label?: L, opts?: SigilOptions): (value: Function, context: any) => void;
 
 /**
  * HOF (class inhancer) that attaches runtime sigil metadata to Sigil class.
@@ -573,6 +604,7 @@ declare function withSigil<S extends Function, L extends string = string>(Class:
  * Use this when the runtime metadata is already present (for example the class
  * is already decorated or was created via `Sigilify`).
  *
+ * @deprecated
  * @typeParam S - Constructor type (should be an ISigil).
  * @typeParam L - Label literal to associate at compile-time.
  * @param Class - The constructor to assert as typed sigil.
@@ -607,10 +639,10 @@ declare function withSigilTyped<S extends Function, L extends string = string>(C
  * This is a lightweight check that verifies the presence of an internal
  * symbol attached to the constructor.
  *
- * @param value - Value to test.
+ * @param ctor - Constructor to test.
  * @returns `true` if `value` is a sigil constructor, otherwise `false`.
  */
-declare function isSigilCtor(value: unknown): value is ISigil;
+declare function isSigilCtor(ctor: unknown): ctor is ISigil;
 /**
  * Runtime predicate that checks whether the provided object is an instance
  * of a sigil class.
@@ -621,7 +653,7 @@ declare function isSigilCtor(value: unknown): value is ISigil;
  * @param obj - The value to test.
  * @returns `true` if `obj` is an instance produced by a sigil constructor.
  */
-declare function isSigilInstance(obj: unknown): obj is ISigilInstance;
+declare function isSigilInstance(obj: unknown): obj is InstanceType<ISigil>;
 /**
  * Check whether the provided constructor was marked as a sigil base constructor.
  *
@@ -630,7 +662,7 @@ declare function isSigilInstance(obj: unknown): obj is ISigilInstance;
  * @param ctor - Constructor to check.
  * @returns `true` if `ctor` is a sigil base constructor.
  */
-declare function isSigilBaseCtor(ctor: Function): boolean;
+declare function isSigilBaseCtor(ctor: Function): ctor is ISigil;
 /**
  * Check whether the provided object is an instance of a sigil base constructor.
  *
@@ -639,7 +671,7 @@ declare function isSigilBaseCtor(ctor: Function): boolean;
  * @param obj - The object to test.
  * @returns `true` if `obj` is an instance of a sigil base constructor.
  */
-declare function isSigilBaseInstance(obj: unknown): obj is ISigilInstance;
+declare function isSigilBaseInstance(obj: unknown): obj is InstanceType<ISigil>;
 /**
  * Returns whether the constructor has been explicitly decorated with `WithSigil`.
  *
@@ -680,9 +712,22 @@ declare function isInheritanceChecked(ctor: Function): boolean;
  * @returns A new abstract constructor that extends `Base` and includes Sigil statics/instance methods.
  * @throws Error if `Base` is already sigilized.
  */
-declare function Sigilify(Base: Constructor, label?: string, opts?: SigilOptions): {
+declare function Sigilify<B extends Constructor, L extends string>(Base: B, label?: L, opts?: SigilOptions): {
     new (...args: any[]): {
-        readonly __SIGIL_BRAND__: Record<string, true>;
+        /**
+         * Compile-time nominal brand that encodes the class label `L` plus parent's brand keys `BrandOf<P>`.
+         *
+         * - Provides a *type-only* unique marker that makes instances nominally
+         *   distinct by label and allows propagation/merging of brand keys across inheritance.
+         * - Runtime: **no runtime value is required**; this property exists only for the type system.
+         *
+         * @remarks
+         * Consumers should not read or set this property at runtime. It is used by helper
+         * types (e.g. `SigilBrandOf`, `TypedSigil`) to extract/propagate compile-time brands.
+         */
+        readonly __SIGIL_BRAND__: {
+            Sigil: true;
+        } & { [K_1 in L]: true; } extends infer T ? { [K in keyof T]: T[K]; } : never;
         /**
          * Returns the human-readable sigil label of this instance's constructor.
          *
@@ -708,7 +753,20 @@ declare function Sigilify(Base: Constructor, label?: string, opts?: SigilOptions
          */
         getSigilTypeSet(): Readonly<Set<symbol>>;
     };
-    readonly __SIGIL_BRAND__: Record<string, true>;
+    /**
+     * Compile-time nominal brand that encodes the class label `L` plus parent's brand keys `BrandOf<P>`.
+     *
+     * - Provides a *type-only* unique marker that makes instances nominally
+     *   distinct by label and allows propagation/merging of brand keys across inheritance.
+     * - Runtime: **no runtime value is required**; this property exists only for the type system.
+     *
+     * @remarks
+     * Consumers should not read or set this property at runtime. It is used by helper
+     * types (e.g. `SigilBrandOf`, `TypedSigil`) to extract/propagate compile-time brands.
+     */
+    readonly __SIGIL_BRAND__: Prettify<{
+        Sigil: true;
+    } & { [K in L]: true; }>;
     /**
      * Class-level human-readable label constant for this sigil constructor.
      */
@@ -772,6 +830,6 @@ declare function Sigilify(Base: Constructor, label?: string, opts?: SigilOptions
      * @returns `true` if `other` has an identical lineage up to the length of this constructor's lineage.
      */
     isOfTypeStrict<T extends ISigil>(this: T, other: unknown): other is InstanceType<T>;
-};
+} & B;
 
-export { DEFAULT_LABEL_REGEX, type GetInstance, type ISigil, type ISigilInstance, type ISigilStatic, REGISTRY, Sigil, type SigilBrandOf, SigilError, type SigilOptions, SigilRegistry, Sigilify, type TypedSigil, WithSigil, getActiveRegistry, isDecorated, isInheritanceChecked, isSigilBaseCtor, isSigilBaseInstance, isSigilCtor, isSigilInstance, typed, updateOptions, withSigil, withSigilTyped };
+export { DEFAULT_LABEL_REGEX, type GetInstance, type ISigil, REGISTRY, Sigil, type SigilBrandOf, SigilError, type SigilOptions, SigilRegistry, Sigilify, type TypedSigil, type UpdateSigilBrand, WithSigil, getActiveRegistry, isDecorated, isInheritanceChecked, isSigilBaseCtor, isSigilBaseInstance, isSigilCtor, isSigilInstance, typed, updateOptions, withSigil, withSigilTyped };

package/dist/index.d.ts

@@ -304,9 +304,9 @@ interface SigilOptions {
  * predicates implemented by the `Sigilify` mixin.
  *
  * @template L - Narrow string literal type representing the label.
- * @template US - Optinal original Untyped Sigil constructor type being augmented.
+ * @template P - Optinal parent to extend its '__SIGIL_BRAND__'.
  */
-interface ISigilStatic<L extends string = string, US extends Function = never> {
+interface ISigilStatic<L extends string = string, P extends Function = never> {
     /**
      * Compile-time nominal brand that encodes the class label `L` plus parent's brand keys `BrandOf<P>`.
      *
@@ -320,7 +320,7 @@ interface ISigilStatic<L extends string = string, US extends Function = never> {
      */
     readonly __SIGIL_BRAND__: Prettify<{
         [k in L]: true;
-    } & SigilBrandOf<US>>;
+    } & SigilBrandOf<P>>;
     /** Class-level label constant (human readable). */
     readonly SigilLabel: string;
     /** Class-level unique symbol used as the runtime type identifier. */
@@ -379,9 +379,9 @@ interface ISigilStatic<L extends string = string, US extends Function = never> {
  * The methods mirror the instance helpers injected by the mixin.
  *
  * @template L - Narrow string literal type for the label returned by `getSigilLabel`.
- * @template US - Optinal original Untyped Sigil constructor type being augmented.
+ * @template P - Optinal parent to extend its '__SIGIL_BRAND__'.
  */
-interface ISigilInstance<L extends string = string, US extends Function = never> {
+interface ISigilInstance<L extends string = string, P extends Function = never> {
     /**
      * Compile-time nominal brand that encodes the class label `L` plus parent's brand keys `BrandOf<P>`.
      *
@@ -395,7 +395,7 @@ interface ISigilInstance<L extends string = string, US extends Function = never>
      */
     readonly __SIGIL_BRAND__: Prettify<{
         [k in L]: true;
-    } & SigilBrandOf<US>>;
+    } & SigilBrandOf<P>>;
     /** Returns human-readable sigil label of the class constructor. */
     getSigilLabel(): string;
     /** Returns runtime sigil type symbol of the class constructor. */
@@ -413,46 +413,59 @@ interface ISigilInstance<L extends string = string, US extends Function = never>
  * by `Sigilify`.
  *
  * @template L - Narrow string literal type for the label.
- * @template US - Optinal original Untyped Sigil constructor type being augmented.
+ * @template P - Optinal parent to extend its '__SIGIL_BRAND__'.
  */
-type ISigil<L extends string = string, US extends Function = never> = Constructor<ISigilInstance<L, US>> & ISigilStatic<L, US>;
+type ISigil<L extends string = string, P extends Function = never> = Constructor<ISigilInstance<L, P>> & ISigilStatic<L, P>;
 /** -----------------------------------------
- *  Helper sigil types
+ *  HOF pattern types
  * ----------------------------------------- */
-/**
- * Extract the compile-time brand map from a sigil constructor `S`.
- *
- * @typeParam S - A sigil constructor type (e.g. `typeof SomeSigilClass`).
- * @returns The brand record carried on the constructor's instance type (e.g. `{ User: true, Admin: true }`).
- *
- * @remarks
- * - This helper is used purely at the type level to compute the set of brand keys
- *   that should be propagated to derived sigils.
- * - If `S` does not carry a `__SIGIL_BRAND__`, the resulting type is `never` and `IfNever<>`
- *   collapses it to an empty record.
- */
-type SigilBrandOf<S> = IfNever<S extends {
-    readonly __SIGIL_BRAND__: infer Brand;
-} ? Prettify<Brand> : never, Record<string, true>>;
 /**
  * Combine an existing sigil constructor type `S` with a **new** label `L`,
  * while inheriting/propagating compile-time brands from an optional parent sigil `P`.
  *
- * @template US - The original Untyped Sigil constructor type being augmented.
+ * @template S - The original Untyped Sigil constructor type being augmented.
  * @template L - The new label literal to associate with the resulting constructor.
  */
-type TypedSigil<US extends Function, L extends string = string> = US & ISigil<L, US>;
+type TypedSigil<S extends Function, L extends string = string> = S & AppendLabel<L> & Constructor<AppendLabel<L>>;
 /**
  * Generic helper extract instance of the class even in protected and private constructors.
  */
 type GetInstance<T> = T extends {
     prototype: infer R;
-} ? Prettify<R & {
+} ? PrettifyBrand<R & {
     __SIGIL_BRAND__: SigilBrandOf<T>;
 }> : never;
+/** Helper to append label into a class. */
+type AppendLabel<L extends string> = {
+    readonly __SIGIL_BRAND__: Prettify<{
+        [K in L]: true;
+    }>;
+};
+/** -----------------------------------------
+ *  Manual pattern types
+ * ----------------------------------------- */
+/** Update '__SIGIL_BRAND__' field when manual typing is used. */
+type UpdateSigilBrand<L extends string, P extends ISigilInstance> = Prettify<SigilBrandOf<P> & {
+    [K in L]: true;
+}>;
 /** -----------------------------------------
  *  Generic types
  * ----------------------------------------- */
+/**
+ * Extract the compile-time brand map from a sigil constructor `S`.
+ *
+ * @typeParam S - A sigil constructor type (e.g. `typeof SomeSigilClass`).
+ * @returns The brand record carried on the constructor's instance type (e.g. `{ User: true, Admin: true }`).
+ *
+ * @remarks
+ * - This helper is used purely at the type level to compute the set of brand keys
+ *   that should be propagated to derived sigils.
+ * - If `S` does not carry a `__SIGIL_BRAND__`, the resulting type is `never` and `IfNever<>`
+ *   collapses it to an empty record.
+ */
+type SigilBrandOf<S> = IfNever<S extends {
+    readonly __SIGIL_BRAND__: infer Brand;
+} ? Brand : never, Record<string, true>>;
 /**
  * Generic type for class constructors used by the Sigil utilities.
  *
@@ -463,10 +476,14 @@ type GetInstance<T> = T extends {
  * @template P - Parameter tuple type for the constructor.
  */
 type Constructor<T = object, P extends any[] = any[]> = new (...args: P) => T;
-/** Helper type to prettify value. */
+/** Helper type to prettify value */
 type Prettify<T> = {
     [K in keyof T]: T[K];
 } & {};
+/** Helper type to prettify value, handles nested '__SIGIL_BRAND__' field */
+type PrettifyBrand<T> = {
+    [K in keyof T]: K extends '__SIGIL_BRAND__' ? PrettifyBrand<T[K]> : T[K];
+} & {};
 /** Helper type to replace 'never' with another type */
 type IfNever<T, R = {}> = [T] extends [never] ? R : T;
 
@@ -478,13 +495,17 @@ type IfNever<T, R = {}> = [T] extends [never] ? R : T;
  */
 declare const Sigil: {
     new (...args: any[]): {
-        readonly __SIGIL_BRAND__: Record<string, true>;
+        readonly __SIGIL_BRAND__: {
+            Sigil: true;
+        };
         getSigilLabel(): string;
         getSigilType(): symbol;
         getSigilTypeLineage(): readonly symbol[];
         getSigilTypeSet(): Readonly<Set<symbol>>;
     };
-    readonly __SIGIL_BRAND__: Record<string, true>;
+    readonly __SIGIL_BRAND__: {
+        Sigil: true;
+    };
     get SigilLabel(): string;
     get SigilType(): symbol;
     get SigilTypeLineage(): readonly symbol[];
@@ -492,7 +513,10 @@ declare const Sigil: {
     isSigilified(obj: unknown): obj is ISigil;
     isOfType<T extends ISigil>(this: T, other: unknown): other is InstanceType<T>;
     isOfTypeStrict<T extends ISigil>(this: T, other: unknown): other is InstanceType<T>;
+} & {
+    new (): {};
 };
+type Sigil = InstanceType<typeof Sigil>;
 /**
  * A sigil variant of the built-in `Error` constructor used by the library
  * to represent Sigil-specific errors.
@@ -502,13 +526,19 @@ declare const Sigil: {
  */
 declare const SigilError: {
     new (...args: any[]): {
-        readonly __SIGIL_BRAND__: Record<string, true>;
+        readonly __SIGIL_BRAND__: {
+            Sigil: true;
+            SigilError: true;
+        };
         getSigilLabel(): string;
         getSigilType(): symbol;
         getSigilTypeLineage(): readonly symbol[];
         getSigilTypeSet(): Readonly<Set<symbol>>;
     };
-    readonly __SIGIL_BRAND__: Record<string, true>;
+    readonly __SIGIL_BRAND__: {
+        Sigil: true;
+        SigilError: true;
+    };
     get SigilLabel(): string;
     get SigilType(): symbol;
     get SigilTypeLineage(): readonly symbol[];
@@ -516,7 +546,8 @@ declare const SigilError: {
     isSigilified(obj: unknown): obj is ISigil;
     isOfType<T extends ISigil>(this: T, other: unknown): other is InstanceType<T>;
     isOfTypeStrict<T extends ISigil>(this: T, other: unknown): other is InstanceType<T>;
-};
+} & ErrorConstructor;
+type SigilError = InstanceType<typeof SigilError>;
 
 /**
  * Class decorator factory that attaches sigil statics to a class constructor.
@@ -543,7 +574,7 @@ declare const SigilError: {
  * @param opts - Options object to override any global options if needed.
  * @returns A class decorator compatible with the ECMAScript decorator context.
  */
-declare function WithSigil<L extends string>(label?: L, opts?: SigilOptions): (value: Function, context: ClassDecoratorContext) => void;
+declare function WithSigil<L extends string>(label?: L, opts?: SigilOptions): (value: Function, context: any) => void;
 
 /**
  * HOF (class inhancer) that attaches runtime sigil metadata to Sigil class.
@@ -573,6 +604,7 @@ declare function withSigil<S extends Function, L extends string = string>(Class:
  * Use this when the runtime metadata is already present (for example the class
  * is already decorated or was created via `Sigilify`).
  *
+ * @deprecated
  * @typeParam S - Constructor type (should be an ISigil).
  * @typeParam L - Label literal to associate at compile-time.
  * @param Class - The constructor to assert as typed sigil.
@@ -607,10 +639,10 @@ declare function withSigilTyped<S extends Function, L extends string = string>(C
  * This is a lightweight check that verifies the presence of an internal
  * symbol attached to the constructor.
  *
- * @param value - Value to test.
+ * @param ctor - Constructor to test.
  * @returns `true` if `value` is a sigil constructor, otherwise `false`.
  */
-declare function isSigilCtor(value: unknown): value is ISigil;
+declare function isSigilCtor(ctor: unknown): ctor is ISigil;
 /**
  * Runtime predicate that checks whether the provided object is an instance
  * of a sigil class.
@@ -621,7 +653,7 @@ declare function isSigilCtor(value: unknown): value is ISigil;
  * @param obj - The value to test.
  * @returns `true` if `obj` is an instance produced by a sigil constructor.
  */
-declare function isSigilInstance(obj: unknown): obj is ISigilInstance;
+declare function isSigilInstance(obj: unknown): obj is InstanceType<ISigil>;
 /**
  * Check whether the provided constructor was marked as a sigil base constructor.
  *
@@ -630,7 +662,7 @@ declare function isSigilInstance(obj: unknown): obj is ISigilInstance;
  * @param ctor - Constructor to check.
  * @returns `true` if `ctor` is a sigil base constructor.
  */
-declare function isSigilBaseCtor(ctor: Function): boolean;
+declare function isSigilBaseCtor(ctor: Function): ctor is ISigil;
 /**
  * Check whether the provided object is an instance of a sigil base constructor.
  *
@@ -639,7 +671,7 @@ declare function isSigilBaseCtor(ctor: Function): boolean;
  * @param obj - The object to test.
  * @returns `true` if `obj` is an instance of a sigil base constructor.
  */
-declare function isSigilBaseInstance(obj: unknown): obj is ISigilInstance;
+declare function isSigilBaseInstance(obj: unknown): obj is InstanceType<ISigil>;
 /**
  * Returns whether the constructor has been explicitly decorated with `WithSigil`.
  *
@@ -680,9 +712,22 @@ declare function isInheritanceChecked(ctor: Function): boolean;
  * @returns A new abstract constructor that extends `Base` and includes Sigil statics/instance methods.
  * @throws Error if `Base` is already sigilized.
  */
-declare function Sigilify(Base: Constructor, label?: string, opts?: SigilOptions): {
+declare function Sigilify<B extends Constructor, L extends string>(Base: B, label?: L, opts?: SigilOptions): {
     new (...args: any[]): {
-        readonly __SIGIL_BRAND__: Record<string, true>;
+        /**
+         * Compile-time nominal brand that encodes the class label `L` plus parent's brand keys `BrandOf<P>`.
+         *
+         * - Provides a *type-only* unique marker that makes instances nominally
+         *   distinct by label and allows propagation/merging of brand keys across inheritance.
+         * - Runtime: **no runtime value is required**; this property exists only for the type system.
+         *
+         * @remarks
+         * Consumers should not read or set this property at runtime. It is used by helper
+         * types (e.g. `SigilBrandOf`, `TypedSigil`) to extract/propagate compile-time brands.
+         */
+        readonly __SIGIL_BRAND__: {
+            Sigil: true;
+        } & { [K_1 in L]: true; } extends infer T ? { [K in keyof T]: T[K]; } : never;
         /**
          * Returns the human-readable sigil label of this instance's constructor.
          *
@@ -708,7 +753,20 @@ declare function Sigilify(Base: Constructor, label?: string, opts?: SigilOptions
          */
         getSigilTypeSet(): Readonly<Set<symbol>>;
     };
-    readonly __SIGIL_BRAND__: Record<string, true>;
+    /**
+     * Compile-time nominal brand that encodes the class label `L` plus parent's brand keys `BrandOf<P>`.
+     *
+     * - Provides a *type-only* unique marker that makes instances nominally
+     *   distinct by label and allows propagation/merging of brand keys across inheritance.
+     * - Runtime: **no runtime value is required**; this property exists only for the type system.
+     *
+     * @remarks
+     * Consumers should not read or set this property at runtime. It is used by helper
+     * types (e.g. `SigilBrandOf`, `TypedSigil`) to extract/propagate compile-time brands.
+     */
+    readonly __SIGIL_BRAND__: Prettify<{
+        Sigil: true;
+    } & { [K in L]: true; }>;
     /**
      * Class-level human-readable label constant for this sigil constructor.
      */
@@ -772,6 +830,6 @@ declare function Sigilify(Base: Constructor, label?: string, opts?: SigilOptions
      * @returns `true` if `other` has an identical lineage up to the length of this constructor's lineage.
      */
     isOfTypeStrict<T extends ISigil>(this: T, other: unknown): other is InstanceType<T>;
-};
+} & B;
 
-export { DEFAULT_LABEL_REGEX, type GetInstance, type ISigil, type ISigilInstance, type ISigilStatic, REGISTRY, Sigil, type SigilBrandOf, SigilError, type SigilOptions, SigilRegistry, Sigilify, type TypedSigil, WithSigil, getActiveRegistry, isDecorated, isInheritanceChecked, isSigilBaseCtor, isSigilBaseInstance, isSigilCtor, isSigilInstance, typed, updateOptions, withSigil, withSigilTyped };
+export { DEFAULT_LABEL_REGEX, type GetInstance, type ISigil, REGISTRY, Sigil, type SigilBrandOf, SigilError, type SigilOptions, SigilRegistry, Sigilify, type TypedSigil, type UpdateSigilBrand, WithSigil, getActiveRegistry, isDecorated, isInheritanceChecked, isSigilBaseCtor, isSigilBaseInstance, isSigilCtor, isSigilInstance, typed, updateOptions, withSigil, withSigilTyped };