[darwin] Simplify MGLStyleLayer initialization and pointer management

Similarly to the previous commit, introduce `-[MGLStyleLayer initWithPendingLayer:]`, allowing the base class to track the owned `_pendingSource` pointer and implement `-addToMapView:` and `-removeFromMapView:` without any casts.

Fixes an issue where `-[MGLStyle layerFromMBGLLayer:]` would wind up creating layers whose `_rawLayer` and `_pendingLayer` held different values.

24 files changed, 275 insertions, 513 deletions

diff --git a/platform/darwin/src/MGLBackgroundStyleLayer.h b/platform/darwin/src/MGLBackgroundStyleLayer.h
index cd218d9fb4..d4de2e2ac7 100644
--- a/platform/darwin/src/MGLBackgroundStyleLayer.h
+++ b/platform/darwin/src/MGLBackgroundStyleLayer.h
@@ -24,6 +24,16 @@ NS_ASSUME_NONNULL_BEGIN
 MGL_EXPORT
 @interface MGLBackgroundStyleLayer : MGLStyleLayer
 
+/**
+Returns a background style layer initialized with an identifier.
+
+After initializing and configuring the style layer, add it to a map view’s
+style using the `-[MGLStyle addLayer:]` or
+`-[MGLStyle insertLayer:belowLayer:]` method.
+
+@param identifier A string that uniquely identifies the source in the style to
+which it is added.
+*/
 - (instancetype)initWithIdentifier:(NSString *)identifier NS_DESIGNATED_INITIALIZER;
 
 #pragma mark - Accessing the Paint Attributes
diff --git a/platform/darwin/src/MGLBackgroundStyleLayer.mm b/platform/darwin/src/MGLBackgroundStyleLayer.mm
index 8f416a0ea2..151d4cadaa 100644
--- a/platform/darwin/src/MGLBackgroundStyleLayer.mm
+++ b/platform/darwin/src/MGLBackgroundStyleLayer.mm
@@ -2,35 +2,28 @@
 // Edit platform/darwin/scripts/generate-style-code.js, then run `make darwin-style-code`.
 
 #import "MGLSource.h"
-#import "MGLMapView_Private.h"
 #import "NSPredicate+MGLAdditions.h"
 #import "NSDate+MGLAdditions.h"
 #import "MGLStyleLayer_Private.h"
+#import "MGLForegroundStyleLayer_Private.h"
 #import "MGLStyleValue_Private.h"
 #import "MGLBackgroundStyleLayer.h"
 
-#include <mbgl/map/map.hpp>
+#include <mbgl/style/transition_options.hpp>
 #include <mbgl/style/layers/background_layer.hpp>
 
 @interface MGLBackgroundStyleLayer ()
 
-@property (nonatomic) mbgl::style::BackgroundLayer *rawLayer;
+@property (nonatomic, readonly) mbgl::style::BackgroundLayer *rawLayer;
 
 @end
 
 @implementation MGLBackgroundStyleLayer
-{
-    std::unique_ptr<mbgl::style::BackgroundLayer> _pendingLayer;
-}
 
 - (instancetype)initWithIdentifier:(NSString *)identifier
 {
-    if (self = [super initWithIdentifier:identifier]) {
-        auto layer = std::make_unique<mbgl::style::BackgroundLayer>(identifier.UTF8String);
-        _pendingLayer = std::move(layer);
-        self.rawLayer = _pendingLayer.get();
-    }
-    return self;
+    auto layer = std::make_unique<mbgl::style::BackgroundLayer>(identifier.UTF8String);
+    return self = [super initWithPendingLayer:std::move(layer)];
 }
 
 - (mbgl::style::BackgroundLayer *)rawLayer
@@ -38,51 +31,6 @@
     return (mbgl::style::BackgroundLayer *)super.rawLayer;
 }
 
-- (void)setRawLayer:(mbgl::style::BackgroundLayer *)rawLayer
-{
-    super.rawLayer = rawLayer;
-}
-
-#pragma mark - Adding to and removing from a map view
-
-- (void)addToMapView:(MGLMapView *)mapView belowLayer:(MGLStyleLayer *)otherLayer
-{
-    if (_pendingLayer == nullptr) {
-        [NSException raise:@"MGLRedundantLayerException"
-            format:@"This instance %@ was already added to %@. Adding the same layer instance " \
-                    "to the style more than once is invalid.", self, mapView.style];
-    }
-
-    if (otherLayer) {
-        const mbgl::optional<std::string> belowLayerId{otherLayer.identifier.UTF8String};
-        mapView.mbglMap->addLayer(std::move(_pendingLayer), belowLayerId);
-    } else {
-        mapView.mbglMap->addLayer(std::move(_pendingLayer));
-    }
-}
-
-- (void)removeFromMapView:(MGLMapView *)mapView
-{
-    if (self.rawLayer != mapView.mbglMap->getLayer(self.identifier.UTF8String)) {
-        return;
-    }
-
-    auto removedLayer = mapView.mbglMap->removeLayer(self.identifier.UTF8String);
-    if (!removedLayer) {
-        return;
-    }
-
-    mbgl::style::BackgroundLayer *layer = dynamic_cast<mbgl::style::BackgroundLayer *>(removedLayer.get());
-    if (!layer) {
-        return;
-    }
-
-    removedLayer.release();
-
-    _pendingLayer = std::unique_ptr<mbgl::style::BackgroundLayer>(layer);
-    self.rawLayer = _pendingLayer.get();
-}
-
 #pragma mark - Accessing the Paint Attributes
 
 - (void)setBackgroundColor:(MGLStyleValue<MGLColor *> *)backgroundColor {
diff --git a/platform/darwin/src/MGLCircleStyleLayer.h b/platform/darwin/src/MGLCircleStyleLayer.h
index 69c823a868..efa18795a7 100644
--- a/platform/darwin/src/MGLCircleStyleLayer.h
+++ b/platform/darwin/src/MGLCircleStyleLayer.h
@@ -79,6 +79,21 @@ typedef NS_ENUM(NSUInteger, MGLCircleTranslationAnchor) {
 MGL_EXPORT
 @interface MGLCircleStyleLayer : MGLVectorStyleLayer
 
+/**
+ Returns a circle style layer initialized with an identifier and source.
+
+ After initializing and configuring the style layer, add it to a map view’s
+ style using the `-[MGLStyle addLayer:]` or
+ `-[MGLStyle insertLayer:belowLayer:]` method.
+
+ @param identifier A string that uniquely identifies the source in the style to
+    which it is added.
+ @param source The source from which to obtain the data to style. If the source
+    has not yet been added to the current style, the behavior is undefined.
+ @return An initialized foreground style layer.
+ */
+- (instancetype)initWithIdentifier:(NSString *)identifier source:(MGLSource *)source NS_DESIGNATED_INITIALIZER;
+
 #pragma mark - Accessing the Paint Attributes
 
 /**
diff --git a/platform/darwin/src/MGLCircleStyleLayer.mm b/platform/darwin/src/MGLCircleStyleLayer.mm
index 330b9cdac0..0370f68bda 100644
--- a/platform/darwin/src/MGLCircleStyleLayer.mm
+++ b/platform/darwin/src/MGLCircleStyleLayer.mm
@@ -2,14 +2,14 @@
 // Edit platform/darwin/scripts/generate-style-code.js, then run `make darwin-style-code`.
 
 #import "MGLSource.h"
-#import "MGLMapView_Private.h"
 #import "NSPredicate+MGLAdditions.h"
 #import "NSDate+MGLAdditions.h"
 #import "MGLStyleLayer_Private.h"
+#import "MGLForegroundStyleLayer_Private.h"
 #import "MGLStyleValue_Private.h"
 #import "MGLCircleStyleLayer.h"
 
-#include <mbgl/map/map.hpp>
+#include <mbgl/style/transition_options.hpp>
 #include <mbgl/style/layers/circle_layer.hpp>
 
 namespace mbgl {
@@ -28,23 +28,16 @@ namespace mbgl {
 
 @interface MGLCircleStyleLayer ()
 
-@property (nonatomic) mbgl::style::CircleLayer *rawLayer;
+@property (nonatomic, readonly) mbgl::style::CircleLayer *rawLayer;
 
 @end
 
 @implementation MGLCircleStyleLayer
-{
-    std::unique_ptr<mbgl::style::CircleLayer> _pendingLayer;
-}
 
 - (instancetype)initWithIdentifier:(NSString *)identifier source:(MGLSource *)source
 {
-    if (self = [super initWithIdentifier:identifier source:source]) {
-        auto layer = std::make_unique<mbgl::style::CircleLayer>(identifier.UTF8String, source.identifier.UTF8String);
-        _pendingLayer = std::move(layer);
-        self.rawLayer = _pendingLayer.get();
-    }
-    return self;
+    auto layer = std::make_unique<mbgl::style::CircleLayer>(identifier.UTF8String, source.identifier.UTF8String);
+    return self = [super initWithPendingLayer:std::move(layer) source:source];
 }
 
 - (mbgl::style::CircleLayer *)rawLayer
@@ -52,11 +45,6 @@ namespace mbgl {
     return (mbgl::style::CircleLayer *)super.rawLayer;
 }
 
-- (void)setRawLayer:(mbgl::style::CircleLayer *)rawLayer
-{
-    super.rawLayer = rawLayer;
-}
-
 - (NSString *)sourceIdentifier
 {
     MGLAssertStyleLayerIsValid();
@@ -93,46 +81,6 @@ namespace mbgl {
     return [NSPredicate mgl_predicateWithFilter:self.rawLayer->getFilter()];
 }
 
-#pragma mark - Adding to and removing from a map view
-
-- (void)addToMapView:(MGLMapView *)mapView belowLayer:(MGLStyleLayer *)otherLayer
-{
-    if (_pendingLayer == nullptr) {
-        [NSException raise:@"MGLRedundantLayerException"
-            format:@"This instance %@ was already added to %@. Adding the same layer instance " \
-                    "to the style more than once is invalid.", self, mapView.style];
-    }
-
-    if (otherLayer) {
-        const mbgl::optional<std::string> belowLayerId{otherLayer.identifier.UTF8String};
-        mapView.mbglMap->addLayer(std::move(_pendingLayer), belowLayerId);
-    } else {
-        mapView.mbglMap->addLayer(std::move(_pendingLayer));
-    }
-}
-
-- (void)removeFromMapView:(MGLMapView *)mapView
-{
-    if (self.rawLayer != mapView.mbglMap->getLayer(self.identifier.UTF8String)) {
-        return;
-    }
-
-    auto removedLayer = mapView.mbglMap->removeLayer(self.identifier.UTF8String);
-    if (!removedLayer) {
-        return;
-    }
-
-    mbgl::style::CircleLayer *layer = dynamic_cast<mbgl::style::CircleLayer *>(removedLayer.get());
-    if (!layer) {
-        return;
-    }
-
-    removedLayer.release();
-
-    _pendingLayer = std::unique_ptr<mbgl::style::CircleLayer>(layer);
-    self.rawLayer = _pendingLayer.get();
-}
-
 #pragma mark - Accessing the Paint Attributes
 
 - (void)setCircleBlur:(MGLStyleValue<NSNumber *> *)circleBlur {
diff --git a/platform/darwin/src/MGLFillStyleLayer.h b/platform/darwin/src/MGLFillStyleLayer.h
index 1f3cfc8af5..89f84185dc 100644
--- a/platform/darwin/src/MGLFillStyleLayer.h
+++ b/platform/darwin/src/MGLFillStyleLayer.h
@@ -52,6 +52,21 @@ typedef NS_ENUM(NSUInteger, MGLFillTranslationAnchor) {
 MGL_EXPORT
 @interface MGLFillStyleLayer : MGLVectorStyleLayer
 
+/**
+ Returns a fill style layer initialized with an identifier and source.
+
+ After initializing and configuring the style layer, add it to a map view’s
+ style using the `-[MGLStyle addLayer:]` or
+ `-[MGLStyle insertLayer:belowLayer:]` method.
+
+ @param identifier A string that uniquely identifies the source in the style to
+    which it is added.
+ @param source The source from which to obtain the data to style. If the source
+    has not yet been added to the current style, the behavior is undefined.
+ @return An initialized foreground style layer.
+ */
+- (instancetype)initWithIdentifier:(NSString *)identifier source:(MGLSource *)source NS_DESIGNATED_INITIALIZER;
+
 #pragma mark - Accessing the Paint Attributes
 
 /**
diff --git a/platform/darwin/src/MGLFillStyleLayer.mm b/platform/darwin/src/MGLFillStyleLayer.mm
index 1322a7a0b6..1abc36892a 100644
--- a/platform/darwin/src/MGLFillStyleLayer.mm
+++ b/platform/darwin/src/MGLFillStyleLayer.mm
@@ -2,14 +2,14 @@
 // Edit platform/darwin/scripts/generate-style-code.js, then run `make darwin-style-code`.
 
 #import "MGLSource.h"
-#import "MGLMapView_Private.h"
 #import "NSPredicate+MGLAdditions.h"
 #import "NSDate+MGLAdditions.h"
 #import "MGLStyleLayer_Private.h"
+#import "MGLForegroundStyleLayer_Private.h"
 #import "MGLStyleValue_Private.h"
 #import "MGLFillStyleLayer.h"
 
-#include <mbgl/map/map.hpp>
+#include <mbgl/style/transition_options.hpp>
 #include <mbgl/style/layers/fill_layer.hpp>
 
 namespace mbgl {
@@ -23,23 +23,16 @@ namespace mbgl {
 
 @interface MGLFillStyleLayer ()
 
-@property (nonatomic) mbgl::style::FillLayer *rawLayer;
+@property (nonatomic, readonly) mbgl::style::FillLayer *rawLayer;
 
 @end
 
 @implementation MGLFillStyleLayer
-{
-    std::unique_ptr<mbgl::style::FillLayer> _pendingLayer;
-}
 
 - (instancetype)initWithIdentifier:(NSString *)identifier source:(MGLSource *)source
 {
-    if (self = [super initWithIdentifier:identifier source:source]) {
-        auto layer = std::make_unique<mbgl::style::FillLayer>(identifier.UTF8String, source.identifier.UTF8String);
-        _pendingLayer = std::move(layer);
-        self.rawLayer = _pendingLayer.get();
-    }
-    return self;
+    auto layer = std::make_unique<mbgl::style::FillLayer>(identifier.UTF8String, source.identifier.UTF8String);
+    return self = [super initWithPendingLayer:std::move(layer) source:source];
 }
 
 - (mbgl::style::FillLayer *)rawLayer
@@ -47,11 +40,6 @@ namespace mbgl {
     return (mbgl::style::FillLayer *)super.rawLayer;
 }
 
-- (void)setRawLayer:(mbgl::style::FillLayer *)rawLayer
-{
-    super.rawLayer = rawLayer;
-}
-
 - (NSString *)sourceIdentifier
 {
     MGLAssertStyleLayerIsValid();
@@ -88,46 +76,6 @@ namespace mbgl {
     return [NSPredicate mgl_predicateWithFilter:self.rawLayer->getFilter()];
 }
 
-#pragma mark - Adding to and removing from a map view
-
-- (void)addToMapView:(MGLMapView *)mapView belowLayer:(MGLStyleLayer *)otherLayer
-{
-    if (_pendingLayer == nullptr) {
-        [NSException raise:@"MGLRedundantLayerException"
-            format:@"This instance %@ was already added to %@. Adding the same layer instance " \
-                    "to the style more than once is invalid.", self, mapView.style];
-    }
-
-    if (otherLayer) {
-        const mbgl::optional<std::string> belowLayerId{otherLayer.identifier.UTF8String};
-        mapView.mbglMap->addLayer(std::move(_pendingLayer), belowLayerId);
-    } else {
-        mapView.mbglMap->addLayer(std::move(_pendingLayer));
-    }
-}
-
-- (void)removeFromMapView:(MGLMapView *)mapView
-{
-    if (self.rawLayer != mapView.mbglMap->getLayer(self.identifier.UTF8String)) {
-        return;
-    }
-
-    auto removedLayer = mapView.mbglMap->removeLayer(self.identifier.UTF8String);
-    if (!removedLayer) {
-        return;
-    }
-
-    mbgl::style::FillLayer *layer = dynamic_cast<mbgl::style::FillLayer *>(removedLayer.get());
-    if (!layer) {
-        return;
-    }
-
-    removedLayer.release();
-
-    _pendingLayer = std::unique_ptr<mbgl::style::FillLayer>(layer);
-    self.rawLayer = _pendingLayer.get();
-}
-
 #pragma mark - Accessing the Paint Attributes
 
 - (void)setFillAntialiased:(MGLStyleValue<NSNumber *> *)fillAntialiased {
diff --git a/platform/darwin/src/MGLForegroundStyleLayer.h b/platform/darwin/src/MGLForegroundStyleLayer.h
index 87763f4634..16a973630e 100644
--- a/platform/darwin/src/MGLForegroundStyleLayer.h
+++ b/platform/darwin/src/MGLForegroundStyleLayer.h
@@ -20,23 +20,7 @@ MGL_EXPORT
 
 #pragma mark Initializing a Style Layer
 
-- (instancetype)init __attribute__((unavailable("Use -initWithIdentifier:source: instead.")));
-- (instancetype)initWithIdentifier:(NSString *)identifier __attribute__((unavailable("Use -initWithIdentifier:source: instead.")));
-
-/**
- Returns a foreground style layer initialized with an identifier and source.
-
- After initializing and configuring the style layer, add it to a map view’s
- style using the `-[MGLStyle addLayer:]` or
- `-[MGLStyle insertLayer:belowLayer:]` method.
-
- @param identifier A string that uniquely identifies the source in the style to
-    which it is added.
- @param source The source from which to obtain the data to style. If the source
-    has not yet been added to the current style, the behavior is undefined.
- @return An initialized foreground style layer.
- */
-- (instancetype)initWithIdentifier:(NSString *)identifier source:(MGLSource *)source NS_DESIGNATED_INITIALIZER;
+- (instancetype)init __attribute__((unavailable("Use -init methods of concrete subclasses instead.")));
 
 #pragma mark Specifying a Style Layer’s Content
 
diff --git a/platform/darwin/src/MGLForegroundStyleLayer.m b/platform/darwin/src/MGLForegroundStyleLayer.m
deleted file mode 100644
index b7a0379af2..0000000000
--- a/platform/darwin/src/MGLForegroundStyleLayer.m
+++ /dev/null
@@ -1,20 +0,0 @@
-#import "MGLForegroundStyleLayer.h"
-#import "MGLSource.h"
-
-@implementation MGLForegroundStyleLayer
-
-- (instancetype)initWithIdentifier:(NSString *)identifier source:(MGLSource *)source {
-    if (self = [super initWithIdentifier:identifier]) {
-        _sourceIdentifier = source.identifier;
-    }
-    return self;
-}
-
-- (NSString *)description {
-    return [NSString stringWithFormat:
-            @"<%@: %p; identifier = %@; sourceIdentifier = %@; visible = %@>",
-            NSStringFromClass([self class]), (void *)self, self.identifier,
-            self.sourceIdentifier, self.visible ? @"YES" : @"NO"];
-}
-
-@end
diff --git a/platform/darwin/src/MGLForegroundStyleLayer.mm b/platform/darwin/src/MGLForegroundStyleLayer.mm
new file mode 100644
index 0000000000..6926dfac1f
--- /dev/null
+++ b/platform/darwin/src/MGLForegroundStyleLayer.mm
@@ -0,0 +1,29 @@
+#import "MGLForegroundStyleLayer.h"
+#import "MGLForegroundStyleLayer_Private.h"
+#import "MGLStyleLayer_Private.h"
+#import "MGLSource.h"
+
+@implementation MGLForegroundStyleLayer
+
+- (instancetype)initWithRawLayer:(mbgl::style::Layer *)rawLayer source:(MGLSource *)source {
+    if (self = [super initWithRawLayer:rawLayer]) {
+        _sourceIdentifier = source.identifier;
+    }
+    return self;
+}
+
+- (instancetype)initWithPendingLayer:(std::unique_ptr<mbgl::style::Layer>)pendingLayer source:(MGLSource *)source {
+    if (self = [super initWithPendingLayer:std::move(pendingLayer)]) {
+        _sourceIdentifier = source.identifier;
+    }
+    return self;
+}
+
+- (NSString *)description {
+    return [NSString stringWithFormat:
+            @"<%@: %p; identifier = %@; sourceIdentifier = %@; visible = %@>",
+            NSStringFromClass([self class]), (void *)self, self.identifier,
+            self.sourceIdentifier, self.visible ? @"YES" : @"NO"];
+}
+
+@end
diff --git a/platform/darwin/src/MGLForegroundStyleLayer_Private.h b/platform/darwin/src/MGLForegroundStyleLayer_Private.h
new file mode 100644
index 0000000000..8b8da6c782
--- /dev/null
+++ b/platform/darwin/src/MGLForegroundStyleLayer_Private.h
@@ -0,0 +1,20 @@
+#import "MGLForegroundStyleLayer.h"
+
+#include <memory>
+
+NS_ASSUME_NONNULL_BEGIN
+
+namespace mbgl {
+    namespace style {
+        class Layer;
+    }
+}
+
+@interface MGLForegroundStyleLayer (Private)
+
+- (instancetype)initWithRawLayer:(mbgl::style::Layer *)rawLayer source:(MGLSource *)source;
+- (instancetype)initWithPendingLayer:(std::unique_ptr<mbgl::style::Layer>)pendingLayer source:(MGLSource *)source;
+
+@end
+
+NS_ASSUME_NONNULL_END
diff --git a/platform/darwin/src/MGLLineStyleLayer.h b/platform/darwin/src/MGLLineStyleLayer.h
index e03f3e347e..4259c8fdb1 100644
--- a/platform/darwin/src/MGLLineStyleLayer.h
+++ b/platform/darwin/src/MGLLineStyleLayer.h
@@ -107,6 +107,21 @@ typedef NS_ENUM(NSUInteger, MGLLineTranslationAnchor) {
 MGL_EXPORT
 @interface MGLLineStyleLayer : MGLVectorStyleLayer
 
+/**
+ Returns a line style layer initialized with an identifier and source.
+
+ After initializing and configuring the style layer, add it to a map view’s
+ style using the `-[MGLStyle addLayer:]` or
+ `-[MGLStyle insertLayer:belowLayer:]` method.
+
+ @param identifier A string that uniquely identifies the source in the style to
+    which it is added.
+ @param source The source from which to obtain the data to style. If the source
+    has not yet been added to the current style, the behavior is undefined.
+ @return An initialized foreground style layer.
+ */
+- (instancetype)initWithIdentifier:(NSString *)identifier source:(MGLSource *)source NS_DESIGNATED_INITIALIZER;
+
 #pragma mark - Accessing the Layout Attributes
 
 /**
diff --git a/platform/darwin/src/MGLLineStyleLayer.mm b/platform/darwin/src/MGLLineStyleLayer.mm
index e37489cf0b..b04b238fe2 100644
--- a/platform/darwin/src/MGLLineStyleLayer.mm
+++ b/platform/darwin/src/MGLLineStyleLayer.mm
@@ -2,14 +2,14 @@
 // Edit platform/darwin/scripts/generate-style-code.js, then run `make darwin-style-code`.
 
 #import "MGLSource.h"
-#import "MGLMapView_Private.h"
 #import "NSPredicate+MGLAdditions.h"
 #import "NSDate+MGLAdditions.h"
 #import "MGLStyleLayer_Private.h"
+#import "MGLForegroundStyleLayer_Private.h"
 #import "MGLStyleValue_Private.h"
 #import "MGLLineStyleLayer.h"
 
-#include <mbgl/map/map.hpp>
+#include <mbgl/style/transition_options.hpp>
 #include <mbgl/style/layers/line_layer.hpp>
 
 namespace mbgl {
@@ -35,23 +35,16 @@ namespace mbgl {
 
 @interface MGLLineStyleLayer ()
 
-@property (nonatomic) mbgl::style::LineLayer *rawLayer;
+@property (nonatomic, readonly) mbgl::style::LineLayer *rawLayer;
 
 @end
 
 @implementation MGLLineStyleLayer
-{
-    std::unique_ptr<mbgl::style::LineLayer> _pendingLayer;
-}
 
 - (instancetype)initWithIdentifier:(NSString *)identifier source:(MGLSource *)source
 {
-    if (self = [super initWithIdentifier:identifier source:source]) {
-        auto layer = std::make_unique<mbgl::style::LineLayer>(identifier.UTF8String, source.identifier.UTF8String);
-        _pendingLayer = std::move(layer);
-        self.rawLayer = _pendingLayer.get();
-    }
-    return self;
+    auto layer = std::make_unique<mbgl::style::LineLayer>(identifier.UTF8String, source.identifier.UTF8String);
+    return self = [super initWithPendingLayer:std::move(layer) source:source];
 }
 
 - (mbgl::style::LineLayer *)rawLayer
@@ -59,11 +52,6 @@ namespace mbgl {
     return (mbgl::style::LineLayer *)super.rawLayer;
 }
 
-- (void)setRawLayer:(mbgl::style::LineLayer *)rawLayer
-{
-    super.rawLayer = rawLayer;
-}
-
 - (NSString *)sourceIdentifier
 {
     MGLAssertStyleLayerIsValid();
@@ -100,46 +88,6 @@ namespace mbgl {
     return [NSPredicate mgl_predicateWithFilter:self.rawLayer->getFilter()];
 }
 
-#pragma mark - Adding to and removing from a map view
-
-- (void)addToMapView:(MGLMapView *)mapView belowLayer:(MGLStyleLayer *)otherLayer
-{
-    if (_pendingLayer == nullptr) {
-        [NSException raise:@"MGLRedundantLayerException"
-            format:@"This instance %@ was already added to %@. Adding the same layer instance " \
-                    "to the style more than once is invalid.", self, mapView.style];
-    }
-
-    if (otherLayer) {
-        const mbgl::optional<std::string> belowLayerId{otherLayer.identifier.UTF8String};
-        mapView.mbglMap->addLayer(std::move(_pendingLayer), belowLayerId);
-    } else {
-        mapView.mbglMap->addLayer(std::move(_pendingLayer));
-    }
-}
-
-- (void)removeFromMapView:(MGLMapView *)mapView
-{
-    if (self.rawLayer != mapView.mbglMap->getLayer(self.identifier.UTF8String)) {
-        return;
-    }
-
-    auto removedLayer = mapView.mbglMap->removeLayer(self.identifier.UTF8String);
-    if (!removedLayer) {
-        return;
-    }
-
-    mbgl::style::LineLayer *layer = dynamic_cast<mbgl::style::LineLayer *>(removedLayer.get());
-    if (!layer) {
-        return;
-    }
-
-    removedLayer.release();
-
-    _pendingLayer = std::unique_ptr<mbgl::style::LineLayer>(layer);
-    self.rawLayer = _pendingLayer.get();
-}
-
 #pragma mark - Accessing the Layout Attributes
 
 - (void)setLineCap:(MGLStyleValue<NSValue *> *)lineCap {
diff --git a/platform/darwin/src/MGLOpenGLStyleLayer.h b/platform/darwin/src/MGLOpenGLStyleLayer.h
index de4fc92b17..bdad5f9d07 100644
--- a/platform/darwin/src/MGLOpenGLStyleLayer.h
+++ b/platform/darwin/src/MGLOpenGLStyleLayer.h
@@ -23,6 +23,8 @@ MGL_EXPORT
 
 @property (nonatomic, weak, readonly) MGLMapView *mapView;
 
+- (instancetype)initWithIdentifier:(NSString *)identifier;
+
 - (void)didMoveToMapView:(MGLMapView *)mapView;
 
 - (void)willMoveFromMapView:(MGLMapView *)mapView;
diff --git a/platform/darwin/src/MGLOpenGLStyleLayer.mm b/platform/darwin/src/MGLOpenGLStyleLayer.mm
index da131b6de8..39eda758eb 100644
--- a/platform/darwin/src/MGLOpenGLStyleLayer.mm
+++ b/platform/darwin/src/MGLOpenGLStyleLayer.mm
@@ -72,7 +72,7 @@ void MGLFinishCustomStyleLayer(void *context) {
  */
 @interface MGLOpenGLStyleLayer ()
 
-@property (nonatomic) mbgl::style::CustomLayer *rawLayer;
+@property (nonatomic, readonly) mbgl::style::CustomLayer *rawLayer;
 
 /**
  The map view whose style currently contains the layer.
@@ -84,9 +84,7 @@ void MGLFinishCustomStyleLayer(void *context) {
 
 @end
 
-@implementation MGLOpenGLStyleLayer {
-    std::unique_ptr<mbgl::style::CustomLayer> _pendingLayer;
-}
+@implementation MGLOpenGLStyleLayer
 
 /**
  Returns an OpenGL style layer object initialized with the given identifier.
@@ -100,26 +98,18 @@ void MGLFinishCustomStyleLayer(void *context) {
  @return An initialized OpenGL style layer.
  */
 - (instancetype)initWithIdentifier:(NSString *)identifier {
-    if (self = [super initWithIdentifier:identifier]) {
-        auto layer = std::make_unique<mbgl::style::CustomLayer>(identifier.UTF8String,
-                                                                MGLPrepareCustomStyleLayer,
-                                                                MGLDrawCustomStyleLayer,
-                                                                MGLFinishCustomStyleLayer,
-                                                                (__bridge void *)self);
-        _pendingLayer = std::move(layer);
-        self.rawLayer = _pendingLayer.get();
-    }
-    return self;
+    auto layer = std::make_unique<mbgl::style::CustomLayer>(identifier.UTF8String,
+                                                            MGLPrepareCustomStyleLayer,
+                                                            MGLDrawCustomStyleLayer,
+                                                            MGLFinishCustomStyleLayer,
+                                                            (__bridge void *)self);
+    return self = [super initWithPendingLayer:std::move(layer)];
 }
 
 - (mbgl::style::CustomLayer *)rawLayer {
     return (mbgl::style::CustomLayer *)super.rawLayer;
 }
 
-- (void)setRawLayer:(mbgl::style::CustomLayer *)rawLayer {
-    super.rawLayer = rawLayer;
-}
-
 #pragma mark - Adding to and removing from a map view
 
 - (void)setMapView:(MGLMapView *)mapView {
@@ -134,22 +124,12 @@ void MGLFinishCustomStyleLayer(void *context) {
 
 - (void)addToMapView:(MGLMapView *)mapView belowLayer:(MGLStyleLayer *)otherLayer {
     self.mapView = mapView;
-    if (otherLayer) {
-        const mbgl::optional<std::string> belowLayerId{ otherLayer.identifier.UTF8String };
-        mapView.mbglMap->addLayer(std::move(_pendingLayer), belowLayerId);
-    } else {
-        mapView.mbglMap->addLayer(std::move(_pendingLayer));
-    }
+    [super addToMapView:mapView belowLayer:otherLayer];
 }
 
 - (void)removeFromMapView:(MGLMapView *)mapView {
-    auto removedLayer = mapView.mbglMap->removeLayer(self.identifier.UTF8String);
+    [super removeFromMapView:mapView];
     self.mapView = nil;
-    if (!removedLayer) {
-        return;
-    }
-    _pendingLayer = std::move(reinterpret_cast<std::unique_ptr<mbgl::style::CustomLayer> &>(removedLayer));
-    self.rawLayer = _pendingLayer.get();
 }
 
 /**
diff --git a/platform/darwin/src/MGLRasterStyleLayer.h b/platform/darwin/src/MGLRasterStyleLayer.h
index 377b7f45cd..f1ccf257a2 100644
--- a/platform/darwin/src/MGLRasterStyleLayer.h
+++ b/platform/darwin/src/MGLRasterStyleLayer.h
@@ -36,6 +36,21 @@ NS_ASSUME_NONNULL_BEGIN
 MGL_EXPORT
 @interface MGLRasterStyleLayer : MGLForegroundStyleLayer
 
+/**
+ Returns a raster style layer initialized with an identifier and source.
+
+ After initializing and configuring the style layer, add it to a map view’s
+ style using the `-[MGLStyle addLayer:]` or
+ `-[MGLStyle insertLayer:belowLayer:]` method.
+
+ @param identifier A string that uniquely identifies the source in the style to
+    which it is added.
+ @param source The source from which to obtain the data to style. If the source
+    has not yet been added to the current style, the behavior is undefined.
+ @return An initialized foreground style layer.
+ */
+- (instancetype)initWithIdentifier:(NSString *)identifier source:(MGLSource *)source NS_DESIGNATED_INITIALIZER;
+
 #pragma mark - Accessing the Paint Attributes
 
 /**
diff --git a/platform/darwin/src/MGLRasterStyleLayer.mm b/platform/darwin/src/MGLRasterStyleLayer.mm
index 80508e4e70..8f5415629a 100644
--- a/platform/darwin/src/MGLRasterStyleLayer.mm
+++ b/platform/darwin/src/MGLRasterStyleLayer.mm
@@ -2,35 +2,28 @@
 // Edit platform/darwin/scripts/generate-style-code.js, then run `make darwin-style-code`.
 
 #import "MGLSource.h"
-#import "MGLMapView_Private.h"
 #import "NSPredicate+MGLAdditions.h"
 #import "NSDate+MGLAdditions.h"
 #import "MGLStyleLayer_Private.h"
+#import "MGLForegroundStyleLayer_Private.h"
 #import "MGLStyleValue_Private.h"
 #import "MGLRasterStyleLayer.h"
 
-#include <mbgl/map/map.hpp>
+#include <mbgl/style/transition_options.hpp>
 #include <mbgl/style/layers/raster_layer.hpp>
 
 @interface MGLRasterStyleLayer ()
 
-@property (nonatomic) mbgl::style::RasterLayer *rawLayer;
+@property (nonatomic, readonly) mbgl::style::RasterLayer *rawLayer;
 
 @end
 
 @implementation MGLRasterStyleLayer
-{
-    std::unique_ptr<mbgl::style::RasterLayer> _pendingLayer;
-}
 
 - (instancetype)initWithIdentifier:(NSString *)identifier source:(MGLSource *)source
 {
-    if (self = [super initWithIdentifier:identifier source:source]) {
-        auto layer = std::make_unique<mbgl::style::RasterLayer>(identifier.UTF8String, source.identifier.UTF8String);
-        _pendingLayer = std::move(layer);
-        self.rawLayer = _pendingLayer.get();
-    }
-    return self;
+    auto layer = std::make_unique<mbgl::style::RasterLayer>(identifier.UTF8String, source.identifier.UTF8String);
+    return self = [super initWithPendingLayer:std::move(layer) source:source];
 }
 
 - (mbgl::style::RasterLayer *)rawLayer
@@ -38,11 +31,6 @@
     return (mbgl::style::RasterLayer *)super.rawLayer;
 }
 
-- (void)setRawLayer:(mbgl::style::RasterLayer *)rawLayer
-{
-    super.rawLayer = rawLayer;
-}
-
 - (NSString *)sourceIdentifier
 {
     MGLAssertStyleLayerIsValid();
@@ -50,46 +38,6 @@
     return @(self.rawLayer->getSourceID().c_str());
 }
 
-#pragma mark - Adding to and removing from a map view
-
-- (void)addToMapView:(MGLMapView *)mapView belowLayer:(MGLStyleLayer *)otherLayer
-{
-    if (_pendingLayer == nullptr) {
-        [NSException raise:@"MGLRedundantLayerException"
-            format:@"This instance %@ was already added to %@. Adding the same layer instance " \
-                    "to the style more than once is invalid.", self, mapView.style];
-    }
-
-    if (otherLayer) {
-        const mbgl::optional<std::string> belowLayerId{otherLayer.identifier.UTF8String};
-        mapView.mbglMap->addLayer(std::move(_pendingLayer), belowLayerId);
-    } else {
-        mapView.mbglMap->addLayer(std::move(_pendingLayer));
-    }
-}
-
-- (void)removeFromMapView:(MGLMapView *)mapView
-{
-    if (self.rawLayer != mapView.mbglMap->getLayer(self.identifier.UTF8String)) {
-        return;
-    }
-
-    auto removedLayer = mapView.mbglMap->removeLayer(self.identifier.UTF8String);
-    if (!removedLayer) {
-        return;
-    }
-
-    mbgl::style::RasterLayer *layer = dynamic_cast<mbgl::style::RasterLayer *>(removedLayer.get());
-    if (!layer) {
-        return;
-    }
-
-    removedLayer.release();
-
-    _pendingLayer = std::unique_ptr<mbgl::style::RasterLayer>(layer);
-    self.rawLayer = _pendingLayer.get();
-}
-
 #pragma mark - Accessing the Paint Attributes
 
 - (void)setMaximumRasterBrightness:(MGLStyleValue<NSNumber *> *)maximumRasterBrightness {
diff --git a/platform/darwin/src/MGLStyle.mm b/platform/darwin/src/MGLStyle.mm
index aa493d9ef7..83ff73e8f9 100644
--- a/platform/darwin/src/MGLStyle.mm
+++ b/platform/darwin/src/MGLStyle.mm
@@ -12,6 +12,7 @@
 
 #import "MGLStyle_Private.h"
 #import "MGLStyleLayer_Private.h"
+#import "MGLForegroundStyleLayer_Private.h"
 #import "MGLSource_Private.h"
 
 #import "NSDate+MGLAdditions.h"
@@ -323,39 +324,35 @@ static NSURL *MGLStyleURL_emerald;
     NSParameterAssert(mbglLayer);
 
     NSString *identifier = @(mbglLayer->getID().c_str());
-    MGLStyleLayer *styleLayer;
+
     if (auto fillLayer = mbglLayer->as<mbgl::style::FillLayer>()) {
         MGLSource *source = [self sourceWithIdentifier:@(fillLayer->getSourceID().c_str())];
-        styleLayer = [[MGLFillStyleLayer alloc] initWithIdentifier:identifier source:source];
+        return [[MGLFillStyleLayer alloc] initWithRawLayer:fillLayer source:source];
     } else if (auto lineLayer = mbglLayer->as<mbgl::style::LineLayer>()) {
         MGLSource *source = [self sourceWithIdentifier:@(lineLayer->getSourceID().c_str())];
-        styleLayer = [[MGLLineStyleLayer alloc] initWithIdentifier:identifier source:source];
+        return [[MGLLineStyleLayer alloc] initWithRawLayer:lineLayer source:source];
     } else if (auto symbolLayer = mbglLayer->as<mbgl::style::SymbolLayer>()) {
         MGLSource *source = [self sourceWithIdentifier:@(symbolLayer->getSourceID().c_str())];
-        styleLayer = [[MGLSymbolStyleLayer alloc] initWithIdentifier:identifier source:source];
+        return [[MGLSymbolStyleLayer alloc] initWithRawLayer:symbolLayer source:source];
     } else if (auto rasterLayer = mbglLayer->as<mbgl::style::RasterLayer>()) {
         MGLSource *source = [self sourceWithIdentifier:@(rasterLayer->getSourceID().c_str())];
-        styleLayer = [[MGLRasterStyleLayer alloc] initWithIdentifier:identifier source:source];
+        return [[MGLRasterStyleLayer alloc] initWithRawLayer:rasterLayer source:source];
     } else if (auto circleLayer = mbglLayer->as<mbgl::style::CircleLayer>()) {
         MGLSource *source = [self sourceWithIdentifier:@(circleLayer->getSourceID().c_str())];
-        styleLayer = [[MGLCircleStyleLayer alloc] initWithIdentifier:identifier source:source];
-    } else if (mbglLayer->is<mbgl::style::BackgroundLayer>()) {
-        styleLayer = [[MGLBackgroundStyleLayer alloc] initWithIdentifier:identifier];
-    } else if (mbglLayer->is<mbgl::style::CustomLayer>()) {
-        styleLayer = self.openGLLayers[identifier];
+        return [[MGLCircleStyleLayer alloc] initWithRawLayer:circleLayer source:source];
+    } else if (auto backgroundLayer = mbglLayer->as<mbgl::style::BackgroundLayer>()) {
+        return [[MGLBackgroundStyleLayer alloc] initWithRawLayer:backgroundLayer];
+    } else if (auto customLayer = mbglLayer->as<mbgl::style::CustomLayer>()) {
+        MGLStyleLayer *styleLayer = self.openGLLayers[identifier];
         if (styleLayer) {
-            NSAssert(styleLayer.rawLayer == mbglLayer->as<mbgl::style::CustomLayer>(), @"%@ wraps a CustomLayer that differs from the one associated with the underlying style.", styleLayer);
+            NSAssert(styleLayer.rawLayer == customLayer, @"%@ wraps a CustomLayer that differs from the one associated with the underlying style.", styleLayer);
             return styleLayer;
         }
-        styleLayer = [[MGLOpenGLStyleLayer alloc] initWithIdentifier:identifier];
+        return [[MGLOpenGLStyleLayer alloc] initWithRawLayer:customLayer];
     } else {
         NSAssert(NO, @"Unrecognized layer type");
         return nil;
     }
-
-    styleLayer.rawLayer = mbglLayer;
-
-    return styleLayer;
 }
 
 - (MGLStyleLayer *)layerWithIdentifier:(NSString *)identifier
diff --git a/platform/darwin/src/MGLStyleLayer.h b/platform/darwin/src/MGLStyleLayer.h
index f81643edd7..d68aee29bc 100644
--- a/platform/darwin/src/MGLStyleLayer.h
+++ b/platform/darwin/src/MGLStyleLayer.h
@@ -27,25 +27,7 @@ MGL_EXPORT
 
 #pragma mark Initializing a Style Layer
 
-- (instancetype)init __attribute__((unavailable("Use -initWithIdentifier: instead.")));
-
-/**
- Returns a style layer object initialized with the given identifier.
-
- The default implementation of this initializer in MGLStyleLayer creates an
- invalid style layer. Call this initializer on `MGLBackgroundStyleLayer` or one of
- the concrete subclasses of `MGLForegroundStyleLayer` to create a valid style
- layer.
-
- After initializing and configuring the style layer, add it to a map view’s
- style using the `-[MGLStyle addLayer:]` or
- `-[MGLStyle insertLayer:belowLayer:]` method.
-
- @param identifier A string that uniquely identifies the layer in the style to
-    which it is added.
- @return An initialized style layer.
- */
-- (instancetype)initWithIdentifier:(NSString *)identifier;
+- (instancetype)init __attribute__((unavailable("Use -init methods of concrete subclasses instead.")));
 
 #pragma mark Identifying a Style Layer
 
diff --git a/platform/darwin/src/MGLStyleLayer.h.ejs b/platform/darwin/src/MGLStyleLayer.h.ejs
index e6c60a76db..a91cde672e 100644
--- a/platform/darwin/src/MGLStyleLayer.h.ejs
+++ b/platform/darwin/src/MGLStyleLayer.h.ejs
@@ -84,7 +84,33 @@ MGL_EXPORT
 %>StyleLayer
 <% if (type === 'background') { -%>
 
+/**
+Returns a <%- type %> style layer initialized with an identifier.
+
+After initializing and configuring the style layer, add it to a map view’s
+style using the `-[MGLStyle addLayer:]` or
+`-[MGLStyle insertLayer:belowLayer:]` method.
+
+@param identifier A string that uniquely identifies the source in the style to
+which it is added.
+*/
 - (instancetype)initWithIdentifier:(NSString *)identifier NS_DESIGNATED_INITIALIZER;
+<% } else { -%>
+
+/**
+ Returns a <%- type %> style layer initialized with an identifier and source.
+
+ After initializing and configuring the style layer, add it to a map view’s
+ style using the `-[MGLStyle addLayer:]` or
+ `-[MGLStyle insertLayer:belowLayer:]` method.
+
+ @param identifier A string that uniquely identifies the source in the style to
+    which it is added.
+ @param source The source from which to obtain the data to style. If the source
+    has not yet been added to the current style, the behavior is undefined.
+ @return An initialized foreground style layer.
+ */
+- (instancetype)initWithIdentifier:(NSString *)identifier source:(MGLSource *)source NS_DESIGNATED_INITIALIZER;
 <% } -%>
 
 <% if (layoutProperties.length) { -%>
diff --git a/platform/darwin/src/MGLStyleLayer.mm b/platform/darwin/src/MGLStyleLayer.mm
index 47f41e0388..c72541526f 100644
--- a/platform/darwin/src/MGLStyleLayer.mm
+++ b/platform/darwin/src/MGLStyleLayer.mm
@@ -1,24 +1,57 @@
 #import "MGLStyleLayer_Private.h"
 #import "MGLMapView_Private.h"
 
+#include <mbgl/map/map.hpp>
 #include <mbgl/style/layer.hpp>
 
 @interface MGLStyleLayer ()
 
-@property (nonatomic) mbgl::style::Layer *rawLayer;
+@property (nonatomic, readonly) mbgl::style::Layer *rawLayer;
 
 @end
 
-@implementation MGLStyleLayer
+@implementation MGLStyleLayer {
+    std::unique_ptr<mbgl::style::Layer> _pendingLayer;
+}
 
-- (instancetype)initWithIdentifier:(NSString *)identifier
-{
+- (instancetype)initWithRawLayer:(mbgl::style::Layer *)rawLayer {
     if (self = [super init]) {
-        _identifier = identifier;
+        _identifier = @(rawLayer->getID().c_str());
+        _rawLayer = rawLayer;
+    }
+    return self;
+}
+
+- (instancetype)initWithPendingLayer:(std::unique_ptr<mbgl::style::Layer>)pendingLayer {
+    if (self = [self initWithRawLayer:pendingLayer.get()]) {
+        _pendingLayer = std::move(pendingLayer);
     }
     return self;
 }
 
+- (void)addToMapView:(MGLMapView *)mapView belowLayer:(MGLStyleLayer *)otherLayer
+{
+    if (_pendingLayer == nullptr) {
+        [NSException raise:@"MGLRedundantLayerException"
+            format:@"This instance %@ was already added to %@. Adding the same layer instance " \
+                    "to the style more than once is invalid.", self, mapView.style];
+    }
+
+    if (otherLayer) {
+        const mbgl::optional<std::string> belowLayerId{otherLayer.identifier.UTF8String};
+        mapView.mbglMap->addLayer(std::move(_pendingLayer), belowLayerId);
+    } else {
+        mapView.mbglMap->addLayer(std::move(_pendingLayer));
+    }
+}
+
+- (void)removeFromMapView:(MGLMapView *)mapView
+{
+    if (self.rawLayer == mapView.mbglMap->getLayer(self.identifier.UTF8String)) {
+        _pendingLayer = mapView.mbglMap->removeLayer(self.identifier.UTF8String);
+    }
+}
+
 - (void)setVisible:(BOOL)visible
 {
     MGLAssertStyleLayerIsValid();
diff --git a/platform/darwin/src/MGLStyleLayer.mm.ejs b/platform/darwin/src/MGLStyleLayer.mm.ejs
index 1e5f3df160..74b67be74a 100644
--- a/platform/darwin/src/MGLStyleLayer.mm.ejs
+++ b/platform/darwin/src/MGLStyleLayer.mm.ejs
@@ -8,14 +8,14 @@
 // Edit platform/darwin/scripts/generate-style-code.js, then run `make darwin-style-code`.
 
 #import "MGLSource.h"
-#import "MGLMapView_Private.h"
 #import "NSPredicate+MGLAdditions.h"
 #import "NSDate+MGLAdditions.h"
 #import "MGLStyleLayer_Private.h"
+#import "MGLForegroundStyleLayer_Private.h"
 #import "MGLStyleValue_Private.h"
 #import "MGL<%- camelize(type) %>StyleLayer.h"
 
-#include <mbgl/map/map.hpp>
+#include <mbgl/style/transition_options.hpp>
 #include <mbgl/style/layers/<%- type.replace('-', '_') %>_layer.hpp>
 <% if (enumProperties) { -%>
 
@@ -50,35 +50,24 @@ namespace mbgl {
 
 @interface MGL<%- camelize(type) %>StyleLayer ()
 
-@property (nonatomic) mbgl::style::<%- camelize(type) %>Layer *rawLayer;
+@property (nonatomic, readonly) mbgl::style::<%- camelize(type) %>Layer *rawLayer;
 
 @end
 
 @implementation MGL<%- camelize(type) %>StyleLayer
-{
-    std::unique_ptr<mbgl::style::<%- camelize(type) %>Layer> _pendingLayer;
-}
 
 <% if (type == 'background') { -%>
 - (instancetype)initWithIdentifier:(NSString *)identifier
 {
-    if (self = [super initWithIdentifier:identifier]) {
-        auto layer = std::make_unique<mbgl::style::<%- camelize(type) %>Layer>(identifier.UTF8String);
-        _pendingLayer = std::move(layer);
-        self.rawLayer = _pendingLayer.get();
-    }
-    return self;
+    auto layer = std::make_unique<mbgl::style::<%- camelize(type) %>Layer>(identifier.UTF8String);
+    return self = [super initWithPendingLayer:std::move(layer)];
 }
 
 <% } else { -%>
 - (instancetype)initWithIdentifier:(NSString *)identifier source:(MGLSource *)source
 {
-    if (self = [super initWithIdentifier:identifier source:source]) {
-        auto layer = std::make_unique<mbgl::style::<%- camelize(type) %>Layer>(identifier.UTF8String, source.identifier.UTF8String);
-        _pendingLayer = std::move(layer);
-        self.rawLayer = _pendingLayer.get();
-    }
-    return self;
+    auto layer = std::make_unique<mbgl::style::<%- camelize(type) %>Layer>(identifier.UTF8String, source.identifier.UTF8String);
+    return self = [super initWithPendingLayer:std::move(layer) source:source];
 }
 
 <% } -%>
@@ -87,11 +76,6 @@ namespace mbgl {
     return (mbgl::style::<%- camelize(type) %>Layer *)super.rawLayer;
 }
 
-- (void)setRawLayer:(mbgl::style::<%- camelize(type) %>Layer *)rawLayer
-{
-    super.rawLayer = rawLayer;
-}
-
 <% if (type !== 'background') { -%>
 - (NSString *)sourceIdentifier
 {
@@ -131,46 +115,6 @@ namespace mbgl {
 }
 
 <% }} -%>
-#pragma mark - Adding to and removing from a map view
-
-- (void)addToMapView:(MGLMapView *)mapView belowLayer:(MGLStyleLayer *)otherLayer
-{
-    if (_pendingLayer == nullptr) {
-        [NSException raise:@"MGLRedundantLayerException"
-            format:@"This instance %@ was already added to %@. Adding the same layer instance " \
-                    "to the style more than once is invalid.", self, mapView.style];
-    }
-
-    if (otherLayer) {
-        const mbgl::optional<std::string> belowLayerId{otherLayer.identifier.UTF8String};
-        mapView.mbglMap->addLayer(std::move(_pendingLayer), belowLayerId);
-    } else {
-        mapView.mbglMap->addLayer(std::move(_pendingLayer));
-    }
-}
-
-- (void)removeFromMapView:(MGLMapView *)mapView
-{
-    if (self.rawLayer != mapView.mbglMap->getLayer(self.identifier.UTF8String)) {
-        return;
-    }
-
-    auto removedLayer = mapView.mbglMap->removeLayer(self.identifier.UTF8String);
-    if (!removedLayer) {
-        return;
-    }
-
-    mbgl::style::<%- camelize(type) %>Layer *layer = dynamic_cast<mbgl::style::<%- camelize(type) %>Layer *>(removedLayer.get());
-    if (!layer) {
-        return;
-    }
-
-    removedLayer.release();
-
-    _pendingLayer = std::unique_ptr<mbgl::style::<%- camelize(type) %>Layer>(layer);
-    self.rawLayer = _pendingLayer.get();
-}
-
 <% if (layoutProperties.length) { -%>
 #pragma mark - Accessing the Layout Attributes
 
diff --git a/platform/darwin/src/MGLStyleLayer_Private.h b/platform/darwin/src/MGLStyleLayer_Private.h
index b5d709a7af..d024a0bb13 100644
--- a/platform/darwin/src/MGLStyleLayer_Private.h
+++ b/platform/darwin/src/MGLStyleLayer_Private.h
@@ -30,6 +30,18 @@ NS_ASSUME_NONNULL_BEGIN
 
 @interface MGLStyleLayer (Private)
 
+/**
+ Initializes and returns a layer with a raw pointer to the backing store,
+ associated with a style.
+ */
+- (instancetype)initWithRawLayer:(mbgl::style::Layer *)rawLayer;
+
+/**
+ Initializes and returns a layer with an owning pointer to the backing store,
+ unassociated from a style.
+ */
+- (instancetype)initWithPendingLayer:(std::unique_ptr<mbgl::style::Layer>)pendingLayer;
+
 @property (nonatomic, readwrite, copy) NSString *identifier;
 
 /**
@@ -39,7 +51,7 @@ NS_ASSUME_NONNULL_BEGIN
  pointer value stays even after ownership of the object is transferred via
  `mbgl::Map addLayer`.
  */
-@property (nonatomic) mbgl::style::Layer *rawLayer;
+@property (nonatomic, readonly) mbgl::style::Layer *rawLayer;
 
 /**
  Adds the mbgl style layer that this object represents to the mbgl map below the
diff --git a/platform/darwin/src/MGLSymbolStyleLayer.h b/platform/darwin/src/MGLSymbolStyleLayer.h
index 7040610093..deaed64817 100644
--- a/platform/darwin/src/MGLSymbolStyleLayer.h
+++ b/platform/darwin/src/MGLSymbolStyleLayer.h
@@ -280,6 +280,21 @@ typedef NS_ENUM(NSUInteger, MGLTextTranslationAnchor) {
 MGL_EXPORT
 @interface MGLSymbolStyleLayer : MGLVectorStyleLayer
 
+/**
+ Returns a symbol style layer initialized with an identifier and source.
+
+ After initializing and configuring the style layer, add it to a map view’s
+ style using the `-[MGLStyle addLayer:]` or
+ `-[MGLStyle insertLayer:belowLayer:]` method.
+
+ @param identifier A string that uniquely identifies the source in the style to
+    which it is added.
+ @param source The source from which to obtain the data to style. If the source
+    has not yet been added to the current style, the behavior is undefined.
+ @return An initialized foreground style layer.
+ */
+- (instancetype)initWithIdentifier:(NSString *)identifier source:(MGLSource *)source NS_DESIGNATED_INITIALIZER;
+
 #pragma mark - Accessing the Layout Attributes
 
 /**
diff --git a/platform/darwin/src/MGLSymbolStyleLayer.mm b/platform/darwin/src/MGLSymbolStyleLayer.mm
index 0f7953311e..502115651c 100644
--- a/platform/darwin/src/MGLSymbolStyleLayer.mm
+++ b/platform/darwin/src/MGLSymbolStyleLayer.mm
@@ -2,14 +2,14 @@
 // Edit platform/darwin/scripts/generate-style-code.js, then run `make darwin-style-code`.
 
 #import "MGLSource.h"
-#import "MGLMapView_Private.h"
 #import "NSPredicate+MGLAdditions.h"
 #import "NSDate+MGLAdditions.h"
 #import "MGLStyleLayer_Private.h"
+#import "MGLForegroundStyleLayer_Private.h"
 #import "MGLStyleValue_Private.h"
 #import "MGLSymbolStyleLayer.h"
 
-#include <mbgl/map/map.hpp>
+#include <mbgl/style/transition_options.hpp>
 #include <mbgl/style/layers/symbol_layer.hpp>
 
 namespace mbgl {
@@ -82,23 +82,16 @@ namespace mbgl {
 
 @interface MGLSymbolStyleLayer ()
 
-@property (nonatomic) mbgl::style::SymbolLayer *rawLayer;
+@property (nonatomic, readonly) mbgl::style::SymbolLayer *rawLayer;
 
 @end
 
 @implementation MGLSymbolStyleLayer
-{
-    std::unique_ptr<mbgl::style::SymbolLayer> _pendingLayer;
-}
 
 - (instancetype)initWithIdentifier:(NSString *)identifier source:(MGLSource *)source
 {
-    if (self = [super initWithIdentifier:identifier source:source]) {
-        auto layer = std::make_unique<mbgl::style::SymbolLayer>(identifier.UTF8String, source.identifier.UTF8String);
-        _pendingLayer = std::move(layer);
-        self.rawLayer = _pendingLayer.get();
-    }
-    return self;
+    auto layer = std::make_unique<mbgl::style::SymbolLayer>(identifier.UTF8String, source.identifier.UTF8String);
+    return self = [super initWithPendingLayer:std::move(layer) source:source];
 }
 
 - (mbgl::style::SymbolLayer *)rawLayer
@@ -106,11 +99,6 @@ namespace mbgl {
     return (mbgl::style::SymbolLayer *)super.rawLayer;
 }
 
-- (void)setRawLayer:(mbgl::style::SymbolLayer *)rawLayer
-{
-    super.rawLayer = rawLayer;
-}
-
 - (NSString *)sourceIdentifier
 {
     MGLAssertStyleLayerIsValid();
@@ -147,46 +135,6 @@ namespace mbgl {
     return [NSPredicate mgl_predicateWithFilter:self.rawLayer->getFilter()];
 }
 
-#pragma mark - Adding to and removing from a map view
-
-- (void)addToMapView:(MGLMapView *)mapView belowLayer:(MGLStyleLayer *)otherLayer
-{
-    if (_pendingLayer == nullptr) {
-        [NSException raise:@"MGLRedundantLayerException"
-            format:@"This instance %@ was already added to %@. Adding the same layer instance " \
-                    "to the style more than once is invalid.", self, mapView.style];
-    }
-
-    if (otherLayer) {
-        const mbgl::optional<std::string> belowLayerId{otherLayer.identifier.UTF8String};
-        mapView.mbglMap->addLayer(std::move(_pendingLayer), belowLayerId);
-    } else {
-        mapView.mbglMap->addLayer(std::move(_pendingLayer));
-    }
-}
-
-- (void)removeFromMapView:(MGLMapView *)mapView
-{
-    if (self.rawLayer != mapView.mbglMap->getLayer(self.identifier.UTF8String)) {
-        return;
-    }
-
-    auto removedLayer = mapView.mbglMap->removeLayer(self.identifier.UTF8String);
-    if (!removedLayer) {
-        return;
-    }
-
-    mbgl::style::SymbolLayer *layer = dynamic_cast<mbgl::style::SymbolLayer *>(removedLayer.get());
-    if (!layer) {
-        return;
-    }
-
-    removedLayer.release();
-
-    _pendingLayer = std::unique_ptr<mbgl::style::SymbolLayer>(layer);
-    self.rawLayer = _pendingLayer.get();
-}
-
 #pragma mark - Accessing the Layout Attributes
 
 - (void)setIconAllowsOverlap:(MGLStyleValue<NSNumber *> *)iconAllowsOverlap {