Complete WidgetKit rendering previews

Author: everettjf

Editor/editorfe/src/scriptWidgetAPI.js

@@ -105,6 +105,7 @@ final class AgentRuntimeBridge {
                 let runtime = ScriptWidgetRuntime(package: package, environments: [
                     "widget-size": size.rawValue,
                     "widget-param": "",
+                    "widget-rendering-mode": "fullColor",
                 ])
 
                 let (element, err) = runtime.executeJSXSyncForWidget(jsx)

Shared/ScriptWidgetRuntime/AI/AgentRuntimeBridge.swift

@@ -508,6 +508,42 @@ class ScriptWidgetRuntime {
 }
 
 extension ScriptWidgetRuntime {
+
+    private func resolveWidgetRootElement(_ root: ScriptWidgetRuntimeElement) -> Result<ScriptWidgetRuntimeElement, ScriptWidgetError> {
+        var current = root
+        var visited = Set<ObjectIdentifier>()
+
+        for _ in 0..<ScriptWidgetRuntimeContract.maximumElementDepth {
+            guard visited.insert(ObjectIdentifier(current)).inserted else {
+                return .failure(.resourceLimit("Root component resolution contains a cycle"))
+            }
+
+            if current.tagAsString() == "Fragment" {
+                let children = current.childrenAsElements()
+                guard children.count == 1, let child = children.first else {
+                    return .success(current)
+                }
+                current = child
+                continue
+            }
+
+            guard current.tagAsString() == nil,
+                  getTypeOfValue(current.tag) == "function" else {
+                return .success(current)
+            }
+
+            var argument = current.getProps()
+            argument["children"] = current.getChildren()
+            guard let resultValue = current.tag.call(withArguments: [argument]),
+                  resultValue.isObject,
+                  let resolved = resultValue.toObject() as? ScriptWidgetRuntimeElement else {
+                return .failure(.scriptError("Root custom component must return a ScriptWidget element"))
+            }
+            current = resolved
+        }
+
+        return .failure(.resourceLimit("Root component resolution exceeds the maximum element depth"))
+    }
 
     func executeJSXSyncForWidget(_ JSX: String) -> (ScriptWidgetRuntimeElement? , ScriptWidgetError?) {
         let trace = ScriptWidgetRuntimeTrace(operation: "widget")
@@ -580,9 +616,15 @@ extension ScriptWidgetRuntime {
 
             let semaphore = DispatchSemaphore(value: 0)
             var resultElement: ScriptWidgetRuntimeElement?
+            var rootResolutionError: ScriptWidgetError?
 
             let renderWidget:@convention(block) (ScriptWidgetRuntimeElement)->Void = { rootElement in
-                resultElement = rootElement
+                switch self.resolveWidgetRootElement(rootElement) {
+                case .success(let resolved):
+                    resultElement = resolved
+                case .failure(let error):
+                    rootResolutionError = error
+                }
                 semaphore.signal()
             }
             self.runtimeContext["$render"] = unsafeBitCast(renderWidget, to: JSValue.self)
@@ -692,6 +734,10 @@ extension ScriptWidgetRuntime {
                     promise(.failure(.scriptException(exceptionInfo)))
                     return
                 }
+                if let rootResolutionError {
+                    promise(.failure(rootResolutionError))
+                    return
+                }
 
                 guard let element = resultElement else {
                     promise(.failure(.scriptError("Transform result is not Element : \(String(describing: resultElement))")))

Shared/ScriptWidgetRuntime/Widget/Runtime/ScriptWidgetRuntime.swift

@@ -144,6 +144,59 @@ final class RuntimeExecutionTests: XCTestCase {
         XCTAssertTrue(text.contains("hello-param"), "expected widget-param in output, got: \(text)")
     }
 
+    func testWidgetRenderingModesReachRuntime() {
+        for mode in ["fullColor", "accented", "vibrant"] {
+            let runtime = makeRuntime(environments: [
+                "widget-size": "medium",
+                "widget-param": "",
+                "widget-rendering-mode": mode,
+            ])
+            let (element, error) = runtime.executeJSXSyncForWidget(
+                "$render(<text>{$getenv(\"widget-rendering-mode\")}</text>);"
+            )
+            XCTAssertNil(error)
+            XCTAssertEqual(element.map(collectText), mode)
+        }
+    }
+
+    func testRootCustomComponentIsResolvedBeforeReturning() {
+        let jsx = """
+        const Shell = ({children}) => <vstack background="#101014">{children}</vstack>;
+        const App = () => <Shell><text>Resolved root</text></Shell>;
+        $render(<App />);
+        """
+        let (element, error) = makeRuntime().executeJSXSyncForWidget(jsx)
+        XCTAssertNil(error, "unexpected error: \(String(describing: error?.displayMessage))")
+        XCTAssertEqual(element?.tagAsString(), "vstack")
+        XCTAssertEqual(element?.getProps()["background"] as? String, "#101014")
+        XCTAssertEqual(element.map(collectText), "Resolved root")
+    }
+
+    func testSingleChildRootFragmentIsResolved() {
+        let (element, error) = makeRuntime().executeJSXSyncForWidget(
+            "$render(<><vstack background=\"navy\"><text>One root</text></vstack></>);"
+        )
+        XCTAssertNil(error)
+        XCTAssertEqual(element?.tagAsString(), "vstack")
+        XCTAssertEqual(element?.getProps()["background"] as? String, "navy")
+    }
+
+    func testMultiChildRootFragmentRemainsAFragment() {
+        let (element, error) = makeRuntime().executeJSXSyncForWidget(
+            "$render(<><text>One</text><text>Two</text></>);"
+        )
+        XCTAssertNil(error)
+        XCTAssertEqual(element?.tagAsString(), "Fragment")
+        XCTAssertEqual(element?.childrenAsElements().count, 2)
+    }
+
+    func testInvalidRootCustomComponentReturnIsRejected() {
+        let (_, error) = makeRuntime().executeJSXSyncForWidget(
+            "const App = () => 'not an element'; $render(<App />);"
+        )
+        XCTAssertTrue(error?.displayMessage.contains("must return a ScriptWidget element") ?? false)
+    }
+
     func testConcurrentRuntimesKeepEnvironmentStateIsolated() {
         let lock = NSLock()
         var rendered: [Int: String] = [:]

Tests/ScriptWidgetRuntimeTests/RuntimeExecutionTests.swift

@@ -790,9 +790,8 @@ Interactive widget toggle. A declared actionID requires a package-relative stora
 
 ## Environment values
 
-- `widgetFamily`
-- `scriptName`
-- `scriptParameter`
+- `widget-size`
+- `widget-param`
 - `widget-rendering-mode`
 - `live-activity-state`
 - `live-activity-surface`

docs/scriptwidget-runtime-api.md

@@ -6,7 +6,9 @@ ScriptWidget packages can use the current WidgetKit presentation, interaction, L
 
 Add `systemExtraLargePortrait` to `supportedFamilies` for the tall extra-large family. At runtime, `$getenv("widget-size")` returns `extraLargePortrait`.
 
-Use `$getenv("widget-rendering-mode")` to adapt to `fullColor`, `accented`, or `vibrant` rendering. Studio exposes the same three preview modes. Set `widgetAccentable={true}` on a component to opt its content into the accent group. Images additionally accept `accentedRenderingMode="accented"`, `"desaturated"`, `"accentedDesaturated"`, or `"fullColor"`.
+Use `$getenv("widget-rendering-mode")` to adapt to `fullColor`, `accented`, or `vibrant` rendering. The iOS editor and macOS Studio expose the same three rendering environments so conditional script branches can be tested. These editor canvases do not reproduce WidgetKit's final system tint pixel-for-pixel; verify the final appearance in a real widget. Set `widgetAccentable={true}` on a component to opt its content into the accent group. Images additionally accept `accentedRenderingMode="accented"`, `"desaturated"`, `"accentedDesaturated"`, or `"fullColor"`.
+
+The root element's `background` is promoted to WidgetKit's container background on supported systems, including when the root is returned through custom components or a single-child Fragment. A Fragment with multiple top-level children has no unique container; wrap those children in one stack when the widget needs a removable container background.
 
 ## Live Activities
 

docs/widgetkit-modern-features.md

@@ -13,6 +13,7 @@ class ScriptCodePreviewDataObject : ObservableObject {
     let model: ScriptModel
     var widgetSizeType: Int
     var scriptParameter: String
+    var widgetRenderingMode: String
 
     @Published var rootElement : ScriptWidgetRuntimeElement
     @Published var previewStatus : String
@@ -27,11 +28,12 @@ class ScriptCodePreviewDataObject : ObservableObject {
     private var previewGeneration = 0
     private var pendingLayoutWorkItem: DispatchWorkItem?
 
-    init(model: ScriptModel, filePath: URL, widgetSizeType: Int, scriptParameter: String) {
+    init(model: ScriptModel, filePath: URL, widgetSizeType: Int, scriptParameter: String, widgetRenderingMode: String = "fullColor") {
         self.model = model
         self.filePath = filePath
         self.widgetSizeType = widgetSizeType
         self.scriptParameter = scriptParameter
+        self.widgetRenderingMode = widgetRenderingMode
 
         self.previewQueue = DispatchQueue(label: "preview-queue", qos: .default)
         self.previewStatus = "Initializing"
@@ -59,6 +61,11 @@ class ScriptCodePreviewDataObject : ObservableObject {
 
         self.layoutElements()
     }
+    func changeWidgetRenderingMode(_ mode: String) {
+        self.widgetRenderingMode = mode
+
+        self.layoutElements()
+    }
     func changeFile(_ filePath: URL) {
         self.filePath = filePath
 
@@ -154,6 +161,7 @@ class ScriptCodePreviewDataObject : ObservableObject {
             let runtime = ScriptWidgetRuntime(package: self.model.package, environments: [
                 "widget-size": widgetSizeString,
                 "widget-param": self.scriptParameter,
+                "widget-rendering-mode": self.widgetRenderingMode,
             ])
 
             let result = runtime.executeJSXSyncForWidget(JSX)

iOS/ScriptWidget/View/CodeEditor/Preview/ScriptCodePreviewDataObject.swift

@@ -16,6 +16,7 @@ struct ScriptCodePreviewView: View {
 
     @State private var scriptParameter = ""
     @State private var scriptParameterApplied = ""
+    @State private var widgetRenderingMode = "fullColor"
     @State private var outputTab = 0
     @FocusState private var scriptParameterIsFocused: Bool
 
@@ -59,6 +60,7 @@ struct ScriptCodePreviewView: View {
                         model: state.model,
                         filePath: state.filePath,
                         scriptParameter: scriptParameterApplied,
+                        widgetRenderingMode: widgetRenderingMode,
                         isDebugMode: isDebugMode
                     )
                 } else {
@@ -175,6 +177,16 @@ struct ScriptCodePreviewView: View {
             Toggle(isOn: $isDebugMode) {
                 Label("Debug Borders", systemImage: "square.dashed")
             }
+
+            Picker("Rendering Environment", selection: $widgetRenderingMode) {
+                Text("Full Color").tag("fullColor")
+                Text("Accented").tag("accented")
+                Text("Vibrant").tag("vibrant")
+            }
+            .pickerStyle(.segmented)
+            .onChange(of: widgetRenderingMode) { value in
+                state.changeWidgetRenderingMode(value)
+            }
 
             HStack {
                 TextField("Parameter", text: $scriptParameter)
@@ -206,6 +218,7 @@ private struct ScriptCodeAllSizesPreview: View {
     let model: ScriptModel
     let filePath: URL
     let scriptParameter: String
+    let widgetRenderingMode: String
     let isDebugMode: Bool
 
     var body: some View {
@@ -217,6 +230,7 @@ private struct ScriptCodeAllSizesPreview: View {
                         filePath: filePath,
                         sizeType: sizeType,
                         scriptParameter: scriptParameter,
+                        widgetRenderingMode: widgetRenderingMode,
                         isDebugMode: isDebugMode
                     )
                 }
@@ -233,17 +247,20 @@ private struct ScriptCodePreviewCard: View {
     @StateObject private var state: ScriptCodePreviewDataObject
     let sizeType: Int
     let scriptParameter: String
+    let widgetRenderingMode: String
     let isDebugMode: Bool
 
-    init(model: ScriptModel, filePath: URL, sizeType: Int, scriptParameter: String, isDebugMode: Bool) {
+    init(model: ScriptModel, filePath: URL, sizeType: Int, scriptParameter: String, widgetRenderingMode: String, isDebugMode: Bool) {
         self.sizeType = sizeType
         self.scriptParameter = scriptParameter
+        self.widgetRenderingMode = widgetRenderingMode
         self.isDebugMode = isDebugMode
         _state = StateObject(wrappedValue: ScriptCodePreviewDataObject(
             model: model,
             filePath: filePath,
             widgetSizeType: sizeType,
-            scriptParameter: scriptParameter
+            scriptParameter: scriptParameter,
+            widgetRenderingMode: widgetRenderingMode
         ))
     }
 
@@ -271,6 +288,9 @@ private struct ScriptCodePreviewCard: View {
         .onChange(of: scriptParameter) { value in
             state.changeWidgetParameter(value)
         }
+        .onChange(of: widgetRenderingMode) { value in
+            state.changeWidgetRenderingMode(value)
+        }
     }
 }
 

iOS/ScriptWidget/View/CodeEditor/Preview/ScriptCodePreviewView.swift

@@ -291,7 +291,7 @@ private struct WidgetConfigurationView: View {
                         Text(mode.title).tag(mode)
                     }
                 }
-                Picker("Rendering", selection: $configuration.renderingMode) {
+                Picker("Rendering Environment", selection: $configuration.renderingMode) {
                     ForEach(StudioPreviewRenderingMode.allCases) { mode in
                         Text(mode.title).tag(mode)
                     }

macOS/ScriptWidgetMac/Editor/EditorPanelView.swift

@@ -359,7 +359,7 @@ struct PreviewView: View {
             }
 
 
-            Picker("Rendering", selection: $configuration.renderingMode) {
+            Picker("Rendering Environment", selection: $configuration.renderingMode) {
                 ForEach(StudioPreviewRenderingMode.allCases) { mode in
                     Text(mode.title).tag(mode)
                 }
@@ -401,6 +401,7 @@ struct PreviewView: View {
                             family: family,
                             scriptModel: scriptModel,
                             scriptParameter: scriptParameterApplied,
+                            renderingMode: configuration.renderingMode,
                             isDebugMode: configuration.debugMode
                         )
                     }
@@ -491,6 +492,7 @@ private struct StudioPreviewTile: View {
     let family: StudioPreviewFamily
     let scriptModel: ScriptModel
     let scriptParameter: String
+    let renderingMode: StudioPreviewRenderingMode
     let isDebugMode: Bool
 
     @StateObject private var data: ScriptCodeRunnerDataObject
@@ -499,16 +501,19 @@ private struct StudioPreviewTile: View {
         family: StudioPreviewFamily,
         scriptModel: ScriptModel,
         scriptParameter: String,
+        renderingMode: StudioPreviewRenderingMode,
         isDebugMode: Bool
     ) {
         self.family = family
         self.scriptModel = scriptModel
         self.scriptParameter = scriptParameter
+        self.renderingMode = renderingMode
         self.isDebugMode = isDebugMode
         _data = StateObject(wrappedValue: ScriptCodeRunnerDataObject(
             file: scriptModel.package,
             widgetSizeType: family.rawValue,
-            scriptParameter: scriptParameter
+            scriptParameter: scriptParameter,
+            renderingMode: renderingMode
         ))
     }
 
@@ -545,6 +550,9 @@ private struct StudioPreviewTile: View {
         .onChange(of: scriptParameter) { _, value in
             data.changeWidgetParameter(value)
         }
+        .onChange(of: renderingMode) { _, value in
+            data.changeRenderingMode(value)
+        }
     }
 }