unify Studio document sessions

Author: everettjf

Editor/editorfe/src/main.js

@@ -36,6 +36,7 @@ import { scriptWidgetDiagnostics, scriptWidgetHover } from "./scriptWidgetLangua
 import { studioTheme } from "./studioTheme.js";
 import { loadDocumentState, saveDocumentState } from "./documentState.js";
 import { DocumentSaveCoordinator, initialStudioState, recoverableDraft, reduceStudioState, removeDraft, shouldWarnBeforeLeaving, writeDraft } from "./webStudioState.js";
+import { WebStudioAPI } from "./webStudioAPI.js";
 import "./style.css";
 
 const isWebStudio = /^https?:$/.test(window.location.protocol);
@@ -299,14 +300,6 @@ async function startWebStudio() {
   let loadedPath = "";
   let saveCoordinator = null;
 
-  class StudioAPIError extends Error {
-    constructor(message, status, body = {}) {
-      super(message);
-      this.status = status;
-      this.body = body;
-    }
-  }
-
   function requirePairing(message = "Session ended. Enter the new code shown on your device.") {
     token = "";
     window.sessionStorage.removeItem("scriptwidget.web-studio.token");
@@ -329,19 +322,8 @@ async function startWebStudio() {
     document.querySelector("#preview-detail").textContent = studioState.preview === "requested" ? "Requested on device" : "Not requested";
   }
 
-  async function api(path, options = {}) {
-    const response = await fetch(path, {
-      ...options,
-      headers: { "Content-Type": "application/json", "X-Studio-Token": token, ...(options.headers || {}) },
-    });
-    const body = await response.json().catch(() => ({}));
-    if (!response.ok) {
-      const error = new StudioAPIError(body.message || `Request failed (${response.status})`, response.status, body);
-      if (response.status === 401 && path !== "/api/v1/pair") requirePairing();
-      throw error;
-    }
-    return body;
-  }
+  const apiClient = new WebStudioAPI({ token: () => token, onUnauthorized: () => requirePairing() });
+  const api = (path, options) => apiClient.request(path, options);
 
   saveCoordinator = new DocumentSaveCoordinator(({ packageID, path, content, baseRevision }) => (
     api("/api/v1/document", {

Editor/editorfe/src/webStudioAPI.js

@@ -0,0 +1,35 @@
+export class StudioAPIError extends Error {
+  constructor(message, status, body = {}) {
+    super(message);
+    this.name = "StudioAPIError";
+    this.status = status;
+    this.body = body;
+  }
+}
+
+export class WebStudioAPI {
+  constructor({ fetchImpl = globalThis.fetch, token = () => "", onUnauthorized = () => {} } = {}) {
+    if (typeof fetchImpl !== "function") throw new TypeError("A fetch implementation is required");
+    this.fetchImpl = fetchImpl;
+    this.token = token;
+    this.onUnauthorized = onUnauthorized;
+  }
+
+  async request(path, options = {}) {
+    const response = await this.fetchImpl(path, {
+      ...options,
+      headers: {
+        "Content-Type": "application/json",
+        "X-Studio-Token": this.token(),
+        ...(options.headers || {}),
+      },
+    });
+    const body = await response.json().catch(() => ({}));
+    if (!response.ok) {
+      const error = new StudioAPIError(body.message || `Request failed (${response.status})`, response.status, body);
+      if (response.status === 401 && path !== "/api/v1/pair") this.onUnauthorized(error);
+      throw error;
+    }
+    return body;
+  }
+}

Editor/editorfe/test/webStudioAPI.test.js

@@ -0,0 +1,47 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { StudioAPIError, WebStudioAPI } from "../src/webStudioAPI.js";
+
+test("WebStudioAPI sends the current token and preserves caller headers", async () => {
+  let captured;
+  const client = new WebStudioAPI({
+    token: () => "fresh-token",
+    fetchImpl: async (path, options) => {
+      captured = { path, options };
+      return { ok: true, json: async () => ({ result: "ok" }) };
+    },
+  });
+  assert.deepEqual(await client.request("/api/v1/session", { headers: { "X-Request-ID": "abc" } }), { result: "ok" });
+  assert.equal(captured.options.headers["X-Studio-Token"], "fresh-token");
+  assert.equal(captured.options.headers["X-Request-ID"], "abc");
+});
+
+test("WebStudioAPI exposes structured server conflicts", async () => {
+  const client = new WebStudioAPI({
+    fetchImpl: async () => ({ ok: false, status: 409, json: async () => ({ message: "Conflict", currentRevision: "r2" }) }),
+  });
+  await assert.rejects(client.request("/api/v1/document"), (error) => {
+    assert.ok(error instanceof StudioAPIError);
+    assert.equal(error.status, 409);
+    assert.equal(error.body.currentRevision, "r2");
+    return true;
+  });
+});
+
+test("WebStudioAPI invalidates unauthorized sessions except failed pairing", async () => {
+  let unauthorized = 0;
+  const client = new WebStudioAPI({
+    onUnauthorized: () => { unauthorized += 1; },
+    fetchImpl: async () => ({ ok: false, status: 401, json: async () => ({}) }),
+  });
+  await assert.rejects(client.request("/api/v1/session"));
+  await assert.rejects(client.request("/api/v1/pair"));
+  assert.equal(unauthorized, 1);
+});
+
+test("WebStudioAPI tolerates an empty non-JSON success response", async () => {
+  const client = new WebStudioAPI({
+    fetchImpl: async () => ({ ok: true, json: async () => { throw new SyntaxError("empty"); } }),
+  });
+  assert.deepEqual(await client.request("/api/v1/session", { method: "DELETE" }), {});
+});

Shared/ScriptWidgetRuntime/Common/ScriptWidgetPackage.swift

@@ -28,6 +28,86 @@ struct FileModel: Identifiable, Hashable {
     var id: String { relativePath }
 }
 
+/// Stable protocol shared by every Studio host. Keeping message names here
+/// prevents the iOS and macOS bridges from drifting independently.
+enum StudioProtocol {
+    static let version = 1
+    static let ready = "studio.ready"
+    static let documentOpen = "document.open"
+    static let documentChanged = "document.changed"
+    static let documentSave = "document.save"
+    static let documentReplace = "document.replace"
+    static let documentSetReadOnly = "document.setReadOnly"
+    static let editorInsert = "editor.insert"
+    static let editorFormat = "editor.format"
+    static let editorGetState = "editor.getState"
+
+    static func envelope(type: String, documentID: String?, payload: [String: Any]) -> [String: Any] {
+        [
+            "protocolVersion": version,
+            "type": type,
+            "documentID": documentID as Any? ?? NSNull(),
+            "payload": payload,
+        ]
+    }
+}
+
+struct StudioDocumentSnapshot: Equatable {
+    let content: String
+    let version: Int
+    let selection: Range<Int>
+
+    init?(state: Any?) {
+        guard
+            let state = state as? [String: Any],
+            let content = state["content"] as? String
+        else { return nil }
+        let version = state["version"] as? Int ?? 0
+        let selection = state["selection"] as? [String: Any]
+        let from = selection?["from"] as? Int ?? 0
+        let to = selection?["to"] as? Int ?? from
+        self.init(content: content, version: version, selection: min(from, to)..<max(from, to))
+    }
+
+    init(content: String, version: Int, selection: Range<Int>) {
+        self.content = content
+        self.version = version
+        self.selection = selection
+    }
+}
+
+/// Owns document identity and the persisted-draft baseline for native Studio
+/// hosts. Web views remain responsible only for transport and presentation.
+final class StudioDocumentSession {
+    private(set) var documentID: String?
+    private(set) var savedContent = ""
+    private let drafts: StudioDraftStore
+
+    init(drafts: StudioDraftStore = .shared) {
+        self.drafts = drafts
+    }
+
+    func open(documentID: String, content: String) -> String {
+        self.documentID = documentID
+        savedContent = content
+        return drafts.recover(documentID: documentID, currentContent: content)?.content ?? content
+    }
+
+    func recordDraft(_ content: String) {
+        guard let documentID else { return }
+        drafts.save(documentID: documentID, baseContent: savedContent, content: content)
+    }
+
+    func markSaved(_ content: String) {
+        savedContent = content
+        if let documentID { drafts.remove(documentID: documentID) }
+    }
+
+    func needsSave(_ content: String) -> Bool {
+        content != savedContent
+    }
+}
+
 /// Crash-safe editor drafts. A draft is restored only while its base file hash
 /// still matches, so an iCloud or external edit always wins over stale local work.
 struct StudioDraftRecord: Codable, Equatable {

Tests/ScriptWidgetRuntimeTests/RuntimeUnitTests.swift

@@ -549,6 +549,42 @@ final class StudioDraftStoreTests: XCTestCase {
         store.save(documentID: "/widget/main.jsx", baseContent: "saved", content: "saved")
         XCTAssertNil(store.recover(documentID: "/widget/main.jsx", currentContent: "saved"))
     }
+
+    func testDocumentSessionRestoresDraftTracksBaselineAndClearsAfterSave() {
+        store.save(documentID: "/widget/main.jsx", baseContent: "saved", content: "draft")
+        let session = StudioDocumentSession(drafts: store)
+
+        XCTAssertEqual(session.open(documentID: "/widget/main.jsx", content: "saved"), "draft")
+        XCTAssertFalse(session.needsSave("saved"))
+        XCTAssertTrue(session.needsSave("draft"))
+
+        session.markSaved("draft")
+        XCTAssertFalse(session.needsSave("draft"))
+        XCTAssertNil(store.recover(documentID: "/widget/main.jsx", currentContent: "draft"))
+    }
+
+    func testDocumentSessionDraftNeverCrossesDocumentIdentity() {
+        let session = StudioDocumentSession(drafts: store)
+        _ = session.open(documentID: "/widget/a.jsx", content: "a")
+        session.recordDraft("draft-a")
+        _ = session.open(documentID: "/widget/b.jsx", content: "b")
+        session.recordDraft("draft-b")
+
+        XCTAssertEqual(store.recover(documentID: "/widget/a.jsx", currentContent: "a")?.content, "draft-a")
+        XCTAssertEqual(store.recover(documentID: "/widget/b.jsx", currentContent: "b")?.content, "draft-b")
+    }
+
+    func testStudioSnapshotNormalizesReverseSelection() throws {
+        let snapshot = try XCTUnwrap(StudioDocumentSnapshot(state: [
+            "content": "hello",
+            "version": 4,
+            "selection": ["from": 5, "to": 2],
+        ]))
+        XCTAssertEqual(snapshot.content, "hello")
+        XCTAssertEqual(snapshot.version, 4)
+        XCTAssertEqual(snapshot.selection, 2..<5)
+        XCTAssertNil(StudioDocumentSnapshot(state: ["version": 1]))
+    }
 }
 
 final class StudioEditorBundleIntegrationTests: XCTestCase {