@byamoah/studio-core 0.1.0-beta.0 → 0.1.0-next.1

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @byamoah/studio-core
 
+## 0.1.0-next.1
+
+### Minor Changes
+
+- 1253d94: Renew active development connections automatically and expire abandoned leases after inactivity. Add shared long-held editor updates and connector job waits to reduce repeated metadata, session and device requests. Make `studio connect` discover project configuration, check the running app, manage an HTTPS preview tunnel, open the private workspace and clean up owned processes on exit, with actionable startup errors.
+- ecdd3db: Add an optional persistence interface to the connection relay so deployment adapters can restore active sessions after a process restart. The default Node relay remains in memory. In-flight connector jobs are not persisted.
+
+### Patch Changes
+
+- @byamoah/studio-state@0.1.0-next.1
+
 ## 0.1.0-beta.0
 
 Initial public prerelease.

package/README.md

@@ -251,42 +251,74 @@ There is not yet a single framework-neutral installation command that generates
 
 ## Connect a local project to hosted Studio
 
-Your laptop makes an outbound connection. The hosted platform does not need direct inbound access to the laptop's filesystem or LAN address.
+Start your app's development server first. For Expo, use a separate terminal:
 
 ```sh
-# Set STUDIO_CONNECT_TOKEN in your shell using the provisioning token
-# supplied by the Studio host. Do not commit it.
-npx --no-install studio connect \
-  --studio https://studio.example.com \
-  --project ./studio.config.mjs
+EXPO_PUBLIC_STUDIO_ORIGIN=https://studio.example.com npx expo start --localhost --port 8081
 ```
 
-Without `--local`, the command starts a loopback development agent, generates project metadata and watches supported source changes. It prints a private editor link. Keep the process running while editing and stop it with Ctrl+C when finished.
+The environment variable configures the application's trusted web bridge origin. Restart Expo after changing it. Providers and inspection bridges still need the one-time integration described above.
 
-To reuse an existing local Studio development server:
+Once the app server is running and `STUDIO_CONNECT_TOKEN` is configured, connecting is one command:
 
 ```sh
-npx --no-install studio connect \
-  --studio https://studio.example.com \
-  --local http://localhost:5173
+npx studio connect --studio https://studio.example.com
 ```
 
+The CLI finds the nearest `studio.config.mjs` or `studio.project.mjs`, including a parent configuration in a monorepo. Its watcher updates the normal `.studio/discovery.json` manifest (or your explicit native manifest path) alongside the hosted metadata; do not run a second `studio dev` watcher for the same project. It generates metadata, checks the app server, starts an HTTPS development tunnel, establishes the hosted connection and opens your private workspace in the browser. No local Studio website is required. It never launches a simulator unless `--simulator` is explicitly supplied.
+
+The managed tunnel uses Cloudflare's official `cloudflared` tool. A compatible installed binary is reused; otherwise a pinned binary is downloaded once, verified against the official release checksum, and cached outside the project. There is no package-install hook that downloads it. No separate Cloudflare account is required for this temporary tunnel. The tool exposes the running app development server until you stop the command. Use an existing transport with `--preview-url` if you prefer another tunnel provider.
+
+The managed startup flow requires the updated CLI. The initial `0.1.0-beta.0` CLI requires explicit transport URLs; use the updated release or a packed development version for the behavior described here.
+
+### Credentials and app URL
+
+Your Studio host supplies a provisioning token. Set `STUDIO_CONNECT_TOKEN` in the shell, or put it in a private `.env.studio.local` file in the directory where you run the command:
+
+```dotenv
+STUDIO_CONNECT_TOKEN=your-private-host-provisioning-token
+```
+
+Ignore that file in Git. The token is not a public application environment variable. Account-based login is not implemented by this command.
+
+Expo projects default to `http://127.0.0.1:8081/`. For another framework or port, configure the application server once:
+
+```js
+connection: {
+  name: "My App",
+  developmentUrl: "http://localhost:3000/",
+}
+```
+
+The full adapter's `preview.developmentUrl` also works. `--app-url` overrides either setting. The command does not start or stop an app server that you own. Missing configuration, an unreachable app, a failed tunnel and a failed host connection produce terminal errors with a next action. A failed startup cleans up the tunnel and agent. Ctrl+C closes the session, stops the owned tunnel and stops discovery; your app server keeps running.
+
+### Options
+
 | Option/configuration | Purpose |
 | --- | --- |
-| `--project PATH` / `STUDIO_PROJECT` | Project config for the standalone agent |
-| `--local URL` / `STUDIO_LOCAL_ORIGIN` | Reuse an existing loopback Studio server |
-| `STUDIO_CONNECT_TOKEN` / `--token` | Hosted provisioning credential; prefer the environment variable |
-| `--preview-url URL` | Public web URL of the running app for iframe preview |
-| `--native-url URL` | Public native app launch URL, such as an Expo tunnel link |
-| `--simulator` | Open the local development link in an already booted Apple simulator |
-| `STUDIO_SIMULATOR_UDID` | Simulator identifier; defaults to `booted` |
-| `--allow-http` | Allow an HTTP loopback host for local testing |
+| `--project PATH` / `STUDIO_PROJECT` | Override automatic project config lookup |
+| `--app-url URL` | Loopback app server to check and tunnel |
+| `--preview-url URL` | Use and check an existing public HTTPS web preview instead of creating a tunnel |
+| `--native-url URL` | Override the native app launch URL; Expo projects with a managed tunnel get an `exps:` link |
+| `--native-only` | Intentionally skip web-server/tunnel setup and use connected-device mode |
+| `--no-open` | Print the private workspace link without opening a browser |
+| `--local URL` / `STUDIO_LOCAL_ORIGIN` | Reuse an existing local Studio server; supply `--app-url` for its preview or `--preview-url` |
+| `STUDIO_CONNECT_TOKEN` / `--token` | Provisioning credential; prefer the environment variable or private env file |
+| `STUDIO_CLOUDFLARED_BIN` | Use an explicit compatible tunnel binary |
+| `STUDIO_CACHE_DIR` | Override the tool download cache directory |
+| `--simulator` | Explicitly open a connection in an already booted Apple simulator |
+| `STUDIO_SIMULATOR_UDID` | Simulator identifier, defaulting to `booted` |
+| `--allow-http` | Permit an HTTP loopback host/preview for local testing |
+
+For a simulator-only workflow, add `--native-only --simulator` to the connection command. On the same laptop, its launch and content URLs remain loopback addresses. Other-network phones need a working public Expo/native transport and correct app bridge integration; a remote device cannot use laptop-local URLs. An externally supplied `--native-url` remains useful for custom development clients or an independently managed transport.
+
+### Renewal and traffic
 
-`--preview-url` and `--native-url` do not create tunnels. Supply URLs from a separately configured tunnel supporting your development server's HTTP and WebSocket traffic. Hosted HTTPS pages need a reachable HTTPS web preview. Configure the application bridge to trust the hosted Studio origin. React Native applications still run through their normal development server.
+The session is a rolling lease, not a fixed development time limit. Authenticated connector activity extends it automatically. A browser tab alone cannot renew it. After an ungraceful disconnect, the session expires after the configured inactivity period, one hour by default. Ctrl+C explicitly revokes it immediately. Restarting a Node host without persistence ends sessions; a host with a session-storage adapter can restore them. Cloudflare's deployment adapter persists lease checkpoints.
 
-For a simulator on the laptop, use loopback addresses. For a phone on the same LAN, use the laptop's reachable network address. For devices on different networks, use publicly reachable app-development and Studio connection URLs. A remote phone cannot access the laptop through `localhost`.
+Hosted Studio shares a single long-held `/updates` request across metadata, draft and device consumers. The server sends only changed sections (document, metadata or devices), and returns an empty response after up to 20 seconds of inactivity. The connector similarly waits up to ten seconds for jobs instead of requesting empty queues several times per second. Background browser tabs pause their update subscription; interrupted connections retry with backoff. Native telemetry can still cause legitimate updates when devices are active.
 
-Private connection links grant development access; share them only with intended participants. Current relay sessions are in memory, expire, and need reconnection after host restart. The connector is development infrastructure, not the installed application's permanent production content endpoint. Restart it after changing configuration or adapter modules that are loaded at startup.
+Older connectors/hosts keep compatible polling behavior. Upgrade the CLI and platform together to get the shared stream and automatic renewal. Private pairing links grant development access; share them only with intended participants. The connector is not an installed application's permanent production content endpoint. Restart it after changing configuration modules loaded at startup.
 
 ## Validate and migrate content
 
@@ -356,6 +388,24 @@ The read endpoint is `/v1/projects/my-app/schemas/1/published.json`; clients sen
 
 The package contains runtime modules and declarations, but not a prebuilt Studio website. Running `/server` requires a separate platform build and project configuration. Hosted connection provisioning and project publication use separate credentials.
 
+### Optional relay session storage
+
+`createConnectionRelay({ token, sessionStorage })` accepts an optional asynchronous storage adapter:
+
+```js
+const sessionStorage = {
+  async load() { /* return an array of previously saved session records */ return []; },
+  async save(record) { /* durably replace the record identified by record.id */ },
+  async delete(id) { /* durably delete this session */ },
+};
+```
+
+An optional `renew(id, { expires, seen })` method can persist a small lease checkpoint without rewriting a large descriptor. Without it, the relay falls back to `save`. Device-only updates stay transient; restoration clears stale device telemetry and issues a fresh update cursor.
+
+Omitting the adapter preserves in-memory Node behavior. The relay saves resumable session records when creating connections and updating snapshots; it deletes them on revocation and expiration. Restored records rebuild empty job queues. Storage errors reject the operation. In-flight requests and queued responses are not durable and may fail across restarts.
+
+Session records include private capability credentials. Keep storage server-side, preserve records without altering them, and restrict access. The adapter owns its storage format, transactions and retention cleanup. No hosting-provider SDK is required by this interface.
+
 ## Troubleshooting
 
 - **`studio` is missing:** install the package in the project and run its local executable. Check the Node version.

package/bin/studio.mjs

@@ -16,7 +16,7 @@ const option = (name) => {
 };
 if (["help", "--help", "-h"].includes(command)) {
   console.log(
-    "Studio CLI\n  studio connect --studio https://studio.example.com [--local http://localhost:5173] [--preview-url https://expo-tunnel] [--native-url exp://expo-tunnel]\n  studio validate --url https://your-api/content [--project path | --config path]\n  studio migrate --document reviewed.json [--project path | --config path]\n  studio init\n  studio discover [--project path | --config path]\n  studio check [--project path | --config path]\n  studio dev [--project path | --config path]\nNode 22.18+ is required. Local package installation supplies this executable; no registry publication is assumed.",
+    "Studio CLI\n  studio connect --studio https://studio.example.com [--project path] [--app-url http://localhost:8081] [--preview-url https://existing-tunnel] [--native-only] [--no-open]\n  studio validate --url https://your-api/content [--project path | --config path]\n  studio migrate --document reviewed.json [--project path | --config path]\n  studio init\n  studio discover [--project path | --config path]\n  studio check [--project path | --config path]\n  studio dev [--project path | --config path]\nNode 22.18+ is required. Local package installation supplies this executable; no registry publication is assumed.",
   );
   process.exit(0);
 }
@@ -46,7 +46,8 @@ if (command === "init") {
 }
 if (command === "connect") {
   const {connectorCli}=await import("../scripts/connector.mjs");
-  await connectorCli(args.slice(1));
+  try { await connectorCli(args.slice(1)); }
+  catch (error) { console.error(`Studio: ${error.message}`); process.exit(1); }
   process.exit(0);
 }
 if (!["discover", "check", "dev", "validate", "migrate"].includes(command))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@byamoah/studio-core",
-  "version": "0.1.0-beta.0",
+  "version": "0.1.0-next.1",
   "type": "module",
   "description": "Studio CLI, discovery compiler and portable inspection runtime",
   "bin": {
@@ -26,7 +26,7 @@
   "dependencies": {
     "@babel/parser": "^7.29.0",
     "@babel/traverse": "^7.29.0",
-    "@byamoah/studio-state": "0.1.0-beta.0",
+    "@byamoah/studio-state": "0.1.0-next.1",
     "typescript": "^6.0.0",
     "@babel/core": "^7.29.13"
   },

package/scripts/connect-preview.mjs

@@ -0,0 +1,124 @@
+import { spawn, execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { access, mkdir, readFile, writeFile, mkdtemp, rm, rename, chmod } from "node:fs/promises";
+import { join, dirname, resolve } from "node:path";
+import { homedir } from "node:os";
+import { createHash } from "node:crypto";
+const exec = promisify(execFile);
+
+export async function findConnectorConfig(start = process.cwd()) {
+  let directory = resolve(start);
+  for (let depth = 0; depth < 8; depth++) {
+    for (const name of ["studio.config.mjs", "studio.project.mjs"]) {
+      const file = join(directory, name);
+      try { await access(file); return file; } catch {}
+    }
+    const parent = dirname(directory);
+    if (parent === directory) break;
+    directory = parent;
+  }
+  throw Error("No Studio project configuration found. Run npx studio init in your app, or pass --project /path/to/studio.project.mjs.");
+}
+export async function ensureTunnelBinary({ signal, cache = process.env.STUDIO_CACHE_DIR ?? join(homedir(), ".cache", "studio", "tools") } = {}) {
+  signal?.throwIfAborted();
+  const explicit = process.env.STUDIO_CLOUDFLARED_BIN;
+  try {
+    const result = await exec(explicit ?? "cloudflared", ["--version"], {timeout:5000, signal});
+    const version = result.stdout.match(/(\d{4})\.(\d+)\.(\d+)/)?.slice(1).map(Number);
+    if (!version || version[0] < 2026 || (version[0] === 2026 && version[1] < 10)) throw Error("outdated");
+    return explicit ?? "cloudflared";
+  }
+  catch { if (explicit) throw Error("STUDIO_CLOUDFLARED_BIN is not a compatible cloudflared binary (2026.10 or newer). Correct that path or remove the override to use automatic installation."); }
+  const version = "2026.10.7";
+  const architecture = { x64:"amd64", arm64:"arm64", arm:"arm" }[process.arch];
+  if (!architecture || !["darwin","linux","win32"].includes(process.platform))
+    throw Error("Automatic tunneling is unavailable on this platform. Supply --preview-url with your HTTPS development URL.");
+  const assetName = `cloudflared-${process.platform === "win32" ? "windows" : process.platform}-${architecture}` +
+    (process.platform === "darwin" ? ".tgz" : process.platform === "win32" ? ".exe" : "");
+  const directory = join(cache, `cloudflared-${version}-${process.platform}-${architecture}`);
+  const binary = join(directory, process.platform === "win32" ? "cloudflared.exe" : "cloudflared");
+  try { await exec(binary,["--version"],{timeout:5000}); return binary; } catch {}
+  console.log("Downloading Cloudflare's tunnel client (one-time setup)…");
+  await mkdir(cache, {recursive:true});
+  const staging = await mkdtemp(join(cache,"download-"));
+  try {
+    const response = await fetch(`https://api.github.com/repos/cloudflare/cloudflared/releases/tags/${version}`, {signal:AbortSignal.any([...(signal?[signal]:[]),AbortSignal.timeout(20000)])});
+    if (!response.ok) throw Error(`Release metadata HTTP ${response.status}`);
+    const asset = (await response.json()).assets?.find(entry => entry.name === assetName);
+    if (!asset || !/^sha256:[a-f0-9]{64}$/.test(asset.digest ?? "")) throw Error("Official asset checksum unavailable");
+    const download = await fetch(asset.browser_download_url, {signal:AbortSignal.any([...(signal?[signal]:[]),AbortSignal.timeout(120000)])});
+    if (!download.ok) throw Error(`Download HTTP ${download.status}`);
+    const bytes = Buffer.from(await download.arrayBuffer());
+    if (`sha256:${createHash("sha256").update(bytes).digest("hex")}` !== asset.digest) throw Error("Tunnel binary checksum mismatch");
+    const target = join(staging, process.platform === "win32" ? "cloudflared.exe" : "cloudflared");
+    if (process.platform === "darwin") {
+      const archive = join(staging,"archive.tgz");await writeFile(archive,bytes);
+      await exec("tar",["-xzf",archive,"-C",staging,"cloudflared"]);
+      await rm(archive);
+    } else await writeFile(target,bytes);
+    await chmod(target,0o700);await exec(target,["--version"],{timeout:5000});
+    try { await rename(staging,directory); }
+    catch (error) { try { await access(binary); } catch { throw error; } }
+    return binary;
+  } catch (error) {
+    throw Error(`Tunnel setup failed: ${error.message}. Check network access to github.com, install cloudflared separately, or use --preview-url with an existing HTTPS tunnel.`);
+  } finally { await rm(staging,{recursive:true,force:true}); }
+}
+export async function verifyAppServer(value, studio) {
+  const url = new URL(value);
+  if (!["http:","https:"].includes(url.protocol) || !["localhost","127.0.0.1","[::1]"].includes(url.hostname) || url.username || url.password)
+    throw Error("The app development URL must use loopback HTTP(S). Supply the public URL through --preview-url instead.");
+  try {
+    const response = await fetch(url,{redirect:"error",signal:AbortSignal.timeout(60000)});
+    if (!response.ok || !(response.headers.get("content-type")??"").includes("text/html")) throw Error(`HTTP ${response.status}; expected an app HTML page`);
+  } catch (error) {
+    throw Error(`App development server is unavailable at ${url.origin}: ${error.message}. Start the app first. For Expo: EXPO_PUBLIC_STUDIO_ORIGIN=${studio} npx expo start --localhost --port ${url.port || "8081"}. Then run studio connect again. For another framework, configure connection.developmentUrl or pass --app-url.`);
+  }
+  return url.href;
+}
+export async function startPreviewTunnel({ url, signal, binary, timeoutMs = 90000, probe = fetch } = {}) {
+  binary ??= await ensureTunnelBinary({ signal });
+  signal?.throwIfAborted();
+  const child = spawn(binary,["tunnel","--url",url,"--no-autoupdate","--no-prechecks","--protocol","http2"],{stdio:["ignore","pipe","pipe"]});
+  let address = "", registered = false, completed = false, buffer = "";
+  const exited = new Promise(resolve => child.once("exit", resolve));
+  const close = async () => {
+    if (!child.pid || child.exitCode !== null || child.signalCode) return;
+    await new Promise(resolve => {
+      const kill = setTimeout(()=>child.kill("SIGKILL"),3000);kill.unref();
+      child.once("exit",()=>{clearTimeout(kill);resolve();});child.kill("SIGTERM");
+    });
+  };
+  const abort = () => { void close(); };
+  signal?.addEventListener("abort",abort,{once:true});
+  if (signal?.aborted) { await close(); throw Error("Connection cancelled."); }
+  try {
+    await new Promise((resolve,reject) => {
+      const timer = setTimeout(()=>reject(Error("Tunnel startup timed out. Check your network/firewall or supply --preview-url.")),timeoutMs);
+      const fail = error => {clearTimeout(timer);reject(error);};
+      child.once("error",()=>fail(Error("Could not start cloudflared. Install it or set STUDIO_CLOUDFLARED_BIN.")));
+      child.once("exit",()=>{if(!completed)fail(Error("Preview tunnel stopped. Check your network or supply --preview-url."));});
+      const output = bytes => {
+        buffer = (buffer+bytes.toString()).slice(-12000);
+        address ||= buffer.match(/https:\/\/[a-z0-9-]+\.trycloudflare\.com/)?.[0] ?? "";
+        registered ||= buffer.includes("Registered tunnel connection");
+        if(address&&registered&&!completed){completed=true;clearTimeout(timer);resolve();}
+      };
+      child.stdout.on("data",output);child.stderr.on("data",output);
+    });
+    let ready = false;
+    for(let attempt=0;attempt<6&&!signal?.aborted;attempt++) {
+      try { const response=await probe(address,{signal:AbortSignal.any([...(signal?[signal]:[]),AbortSignal.timeout(20000)])});
+        if(response.ok){ready=true;break;} }catch{}
+      await new Promise(resolve=>setTimeout(resolve,500));
+    }
+    if(!ready)throw Error("The HTTPS tunnel is connected but the app is not reachable. Check the development server, then retry studio connect.");
+    return {url:address+"/",close:async()=>{signal?.removeEventListener("abort",abort);await close();},
+      exited};
+  }catch(error){signal?.removeEventListener("abort",abort);await close();throw error;}
+}
+export async function openStudioBrowser(url) {
+  const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "rundll32" : "xdg-open";
+  const args = process.platform === "win32" ? ["url.dll,FileProtocolHandler",url] : [url];
+  await exec(command,args,{timeout:10000});
+}

package/scripts/connection-relay.mjs

@@ -1,4 +1,4 @@
-import { randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
+import { createHash, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 const hex = () => randomBytes(24).toString("hex");
 const same = (a, b) => {
   const x = Buffer.from(a ?? ""),
@@ -20,6 +20,7 @@ export function createConnectionRelay({
   ttlMs = 60 * 60 * 1000,
   timeoutMs = 15000,
   maxSessions = 8,
+  sessionStorage,
 } = {}) {
   const sessions = new Map();
   const close = (entry) => {
@@ -34,10 +35,13 @@ export function createConnectionRelay({
       });
     }
     entry.jobs.clear();
+    for (const wake of entry.updateWaiters ?? []) wake();
+    for (const wake of entry.pollWaiters ?? []) wake();
   };
-  const clean = () => {
+  const clean = async () => {
     for (const [id, entry] of sessions)
       if (Date.now() > entry.expires) {
+        await sessionStorage?.delete(id);
         close(entry);
         sessions.delete(id);
       }
@@ -53,6 +57,49 @@ export function createConnectionRelay({
     typeof value.name === "string" &&
     value.session?.document &&
     typeof value.session?.revision === "string";
+  // Persist only resumable session data. In-flight jobs are intentionally ephemeral.
+  const snapshot = ({ id, editor, device, connector, descriptor, expires, seen, origin, version }) =>
+    ({ id, editor, device, connector, descriptor, expires, seen, origin, version });
+  let restored;
+  const restore = () => restored ??= (async () => {
+    if (!sessionStorage) return;
+    for (const entry of await sessionStorage.load()) {
+      if (!entry || !/^[a-f0-9-]{36}$/.test(entry.id) ||
+          ![entry.editor, entry.device, entry.connector].every(value => /^[a-f0-9]{48}$/.test(value)) ||
+          !Number.isFinite(entry.expires) || !Number.isFinite(entry.seen) ||
+          !validDescriptor(entry.descriptor) || typeof entry.origin !== "string")
+        throw Error("Invalid persisted relay session.");
+      const restoredEntry = { ...entry, version: randomUUID(), descriptor: { ...entry.descriptor, devices: [] }, persistedUntil: entry.expires, jobs: new Map(), updateWaiters: new Set(), pollWaiters: new Set(), history: new Map() };
+      remember(restoredEntry); sessions.set(entry.id, restoredEntry);
+    }
+  })().catch(error => { restored = undefined; throw error; });
+  const wait = (set, duration) => new Promise(resolve => {
+    const wake = () => { clearTimeout(timer); set.delete(wake); resolve(); };
+    const timer = setTimeout(wake, duration);
+    set.add(wake);
+  });
+  const capabilities = { updates: 1, longPoll: 1, renewal: 1 };
+  const digest = value => createHash("sha256").update(JSON.stringify(value ?? null)).digest("hex");
+  function remember(entry) {
+    entry.history.set(entry.version, {
+      metadata: entry.descriptor.manifest.buildId + digest(entry.descriptor.resourceUrls),
+      session: digest(entry.descriptor.session),
+      devices: digest(entry.descriptor.devices),
+    });
+    while (entry.history.size > 32) entry.history.delete(entry.history.keys().next().value);
+  }
+  function editorState(entry, after) {
+    const previous = entry.history.get(after), current = entry.history.get(entry.version);
+    if (previous) return {
+      projectId: entry.descriptor.projectId, version: entry.version, expiresAt: entry.expires,
+      ...(previous.metadata !== current.metadata ? { manifest: entry.descriptor.manifest, resourceUrls: entry.descriptor.resourceUrls } : {}),
+      ...(previous.session !== current.session ? { session: publicSession(entry, entry.origin) } : {}),
+      ...(previous.devices !== current.devices ? { devices: entry.descriptor.devices ?? [] } : {}),
+    };
+    return { ...entry.descriptor, version: entry.version,
+      capabilities: { ...capabilities, updates: entry.descriptor.capabilities?.updates === 1 ? 1 : 0 },
+      devices: entry.descriptor.devices ?? [], session: publicSession(entry, entry.origin), expiresAt: entry.expires };
+  }
   function publicSession(entry, origin) {
     const { descriptor: d } = entry,
       prefix = `/__studio/dev/${entry.editor}`,
@@ -113,6 +160,7 @@ export function createConnectionRelay({
         ),
       };
       entry.jobs.set(id, job);
+      for (const wake of entry.pollWaiters) wake();
     });
   }
   return async (req, res) => {
@@ -123,7 +171,8 @@ export function createConnectionRelay({
       !route.startsWith("/__studio/dev/")
     )
       return false;
-    clean();
+    await restore();
+    await clean();
     const json = (status, value) => {
       res.writeHead(status, {
         "Content-Type": "application/json",
@@ -212,14 +261,22 @@ export function createConnectionRelay({
           expires: Date.now() + ttlMs,
           seen: Date.now(),
           jobs: new Map(),
+          updateWaiters: new Set(),
+          pollWaiters: new Set(),
+          version: randomUUID(),
+          history: new Map(),
+          persistedUntil: Date.now() + ttlMs,
           origin: publicOrigin,
         };
+      remember(entry);
+      await sessionStorage?.save(snapshot(entry));
       sessions.set(id, entry);
       return json(201, {
         id,
         connector: entry.connector,
         editorUrl: `${publicOrigin}/?connection=${id}#studio=${entry.editor}`,
         expiresAt: entry.expires,
+        capabilities,
       });
     }
     const control =
@@ -233,13 +290,26 @@ export function createConnectionRelay({
         !same(req.headers.authorization, `Bearer ${entry.connector}`)
       )
         return json(401, { error: "Connection unavailable." });
-      entry.seen = Date.now();
+      const lease = { seen: Date.now(), expires: Date.now() + ttlMs };
+      if (lease.expires - entry.persistedUntil >= Math.min(60_000, ttlMs / 4)) {
+        if (sessionStorage?.renew) await sessionStorage.renew(entry.id, lease);
+        else await sessionStorage?.save(snapshot({ ...entry, ...lease }));
+        entry.persistedUntil = lease.expires;
+      }
+      Object.assign(entry, lease);
       if (!control[2] && req.method === "DELETE") {
+        await sessionStorage?.delete(entry.id);
         close(entry);
         sessions.delete(entry.id);
         return json(200, { closed: true });
       }
       if (control[2] === "poll" && req.method === "GET") {
+        const duration = Math.min(10000, Math.max(0, Number(url.searchParams.get("wait")) || 0));
+        if (duration && ![...entry.jobs.values()].some(job => !job.sent)) {
+          if (entry.pollWaiters.size >= 2) return json(429, { error: "Connector poll already pending." });
+          await wait(entry.pollWaiters, duration);
+        }
+        if (!sessions.has(entry.id)) return json(410, { error: "Connection closed." });
         const jobs = [...entry.jobs.values()]
           .filter((job) => !job.sent)
           .slice(0, 8);
@@ -263,7 +333,15 @@ export function createConnectionRelay({
           return json(422, {
             error: "Project identity cannot change within a connection.",
           });
+        const nextVersion = randomUUID();
+        const durableChanged = JSON.stringify({ ...value, devices: undefined }) !==
+          JSON.stringify({ ...entry.descriptor, devices: undefined });
+        if (durableChanged)
+          await sessionStorage?.save(snapshot({ ...entry, descriptor: value, version: nextVersion }));
         entry.descriptor = value;
+        entry.version = nextVersion;
+        remember(entry);
+        for (const wake of entry.updateWaiters) wake();
         return json(200, { saved: true });
       }
       if (control[2] === "results" && req.method === "POST") {
@@ -300,17 +378,26 @@ export function createConnectionRelay({
       (value) => same(value.editor, match[1]) || same(value.device, match[1]),
     );
     if (!entry)
-      return ["/bootstrap", "/session", "/metadata.json"].includes(match[2])
+      return ["/bootstrap", "/session", "/metadata.json", "/updates"].includes(match[2])
         ? json(410, { error: "Connection expired. Reconnect from the laptop." })
         : false;
     const editor = same(entry.editor, match[1]),
       path = match[2];
     if (editor && req.method === "GET" && path === "/bootstrap")
-      return json(200, {
-        ...entry.descriptor,
-        session: publicSession(entry, entry.origin),
-        expiresAt: entry.expires,
-      });
+      return json(200, editorState(entry));
+    if (editor && req.method === "GET" && path === "/updates") {
+      const duration = Math.min(20000, Math.max(0, Number(url.searchParams.get("wait")) || 0));
+      if (url.searchParams.get("after") === entry.version && duration) {
+        if (entry.updateWaiters.size >= 8) return json(429, { error: "Too many editor subscriptions." });
+        await wait(entry.updateWaiters, duration);
+      }
+      if (!sessions.has(entry.id) || Date.now() > entry.expires)
+        return json(410, { error: "Connection expired. Reconnect from the laptop." });
+      if (url.searchParams.get("after") === entry.version) {
+        res.writeHead(204, { "Cache-Control": "no-store" }); res.end(); return true;
+      }
+      return json(200, editorState(entry, url.searchParams.get("after")));
+    }
     if (editor && req.method === "GET" && path === "/session") {
       res.setHeader("ETag", `"${entry.descriptor.session.revision}"`);
       if (

package/scripts/connector-agent.mjs

@@ -35,6 +35,7 @@ export async function createConnectorAgent(configFile) {
     state: {
       ...original.state,
       directory,
+      nativeManifestFile: original.state?.nativeManifestFile ?? pathToFileURL(resolve(directory, "discovery.json")),
       authoring: original.state?.authoring ?? {
         snapshotFile: pathToFileURL(
           resolve(directory, "content.snapshot.json"),
@@ -144,9 +145,10 @@ export async function createConnectorAgent(configFile) {
       again = false;
       try {
         const before = await fingerprint();
-        manifest = await generateDiscovery(project, publicDir);
-        lastFingerprint = before;
+        const next = await generateDiscovery(project, publicDir);
         await channel.refresh();
+        manifest = next;
+        lastFingerprint = before;
       } catch {
         process.stderr.write(
           "Studio discovery needs attention. Previous local content is preserved.\n",

package/scripts/connector.mjs

@@ -19,6 +19,8 @@ export async function startConnector({
   allowHttp = false,
   onConnected = () => {},
   signal,
+  syncIntervalMs = 1000,
+  pollWaitMs = 10000,
 } = {}) {
   if (!studio)
     throw Error("Use studio connect --studio https://studio.example.com.");
@@ -56,17 +58,20 @@ export async function startConnector({
         "Remote devices need a publicly reachable secure Expo tunnel.",
       );
   }
+  const connectionController = new AbortController();
   const request = async (url, options = {}) => {
     const response = await fetch(url, {
       ...options,
       redirect: "error",
       signal: AbortSignal.any([
         ...(signal ? [signal] : []),
-        AbortSignal.timeout(20000),
+        ...(options.signal ? [options.signal] : []),
+        connectionController.signal,
+        AbortSignal.timeout(25000),
       ]),
     });
     if (!response.ok)
-      throw Error(`Connector service returned ${response.status}.`);
+      throw Object.assign(Error(`Connector service returned ${response.status}.`), {status:response.status});
     return response.json();
   };
   let info,
@@ -101,6 +106,7 @@ export async function startConnector({
     }
     return {
       projectId: info.id,
+      capabilities: { updates: 1 },
       name: info.name,
       channel: info.channel,
       resourceUrls,
@@ -113,6 +119,10 @@ export async function startConnector({
         document: session.document,
         hasDraft: session.hasDraft,
       },
+      devices: await request(new URL(session.writeUrl.replace(/\/draft$/, "") + "/devices", origin))
+        .then(payload => (payload.devices ?? []).map(device => ({ ...device,
+          lastSeen: Math.floor((device.lastSeen ?? 0) / 10000) * 10000 })))
+        .catch(() => []),
       previewUrl: previewUrl ?? null,
       nativeUrl: nativeUrl ?? null,
     };
@@ -126,6 +136,13 @@ export async function startConnector({
     },
     body: JSON.stringify({ publicOrigin: remote.origin, descriptor }),
   });
+  let editor;
+  try { editor = new URL(created.editorUrl); } catch { throw Error("Studio returned an invalid workspace URL."); }
+  if (!/^[a-f0-9-]{36}$/.test(created.id) || !/^[a-f0-9]{48}$/.test(created.connector) ||
+      !Number.isFinite(created.expiresAt) || editor.origin !== remote.origin || editor.pathname !== "/" ||
+      editor.username || editor.password || editor.searchParams.get("connection") !== created.id ||
+      !/^[a-f0-9]{48}$/.test(new URLSearchParams(editor.hash.slice(1)).get("studio") ?? ""))
+    throw Error("Studio returned an invalid connection handshake. Check the host URL and retry.");
   const base = new URL(`/__studio/connect/${created.id}`, remote).href,
     headers = {
       Authorization: `Bearer ${created.connector}`,
@@ -175,7 +192,7 @@ export async function startConnector({
       headers: job.headers,
       ...(job.method === "POST" ? { body: job.body } : {}),
       redirect: "error",
-      signal: AbortSignal.timeout(12000),
+      signal: AbortSignal.any([connectionController.signal, AbortSignal.timeout(12000)]),
     });
     const bytes = Buffer.from(await response.arrayBuffer());
     if (bytes.length > 7_000_000)
@@ -191,125 +208,149 @@ export async function startConnector({
       body: bytes.toString("base64"),
     };
   }
+  let leaseUntil = created.expiresAt;
+  const lifetime = connectionController;
+  const stop = () => { stopped = true; lifetime.abort(); };
+  signal?.addEventListener("abort", stop, { once: true });
+  const pause = (duration) => new Promise(resolve => {
+    if (lifetime.signal.aborted) return resolve();
+    const finish = () => { clearTimeout(timer); lifetime.signal.removeEventListener("abort", finish); resolve(); };
+    const timer = setTimeout(finish, duration);
+    lifetime.signal.addEventListener("abort", finish, {once:true});
+  });
+  let lastWarning = 0;
+  const warn = () => {
+    if (!allowHttp && Date.now() - lastWarning > 10000) {
+      process.stderr.write("Studio connection interrupted; retrying. Local development remains available.\n");
+      lastWarning = Date.now();
+    }
+  };
+  const sync = async () => {
+    while (!stopped && !signal?.aborted) {
+      try {
+        const serialized = JSON.stringify(await snapshot());
+        if (serialized !== last) {
+          await request(base + "/snapshot", {method:"POST",headers,body:serialized});
+          last = serialized;
+        }
+      } catch { if (!stopped) warn(); }
+      await pause(syncIntervalMs);
+    }
+  };
   const done = (async () => {
+    const updating = sync();
+    let failures = 0;
     try {
-      while (!stopped && !signal?.aborted && Date.now() < created.expiresAt) {
+      while (!stopped && !signal?.aborted) {
         try {
-          const next = await snapshot(),
-            serialized = JSON.stringify(next);
-          if (serialized !== last) {
-            await request(base + "/snapshot", {
-              method: "POST",
-              headers,
-              body: serialized,
-            });
-            last = serialized;
-          }
-          const { jobs } = await request(base + "/poll", { headers });
-          await Promise.all(
-            (jobs ?? []).map(async (job) => {
-              let result;
-              try {
-                result = await perform(job);
-              } catch {
-                result = {
-                  id: job.id,
-                  status: 502,
-                  headers: { "content-type": "application/json" },
-                  body: Buffer.from(
-                    JSON.stringify({
-                      error: "Local development service unavailable.",
-                    }),
-                  ).toString("base64"),
-                };
-              }
-              await request(base + "/results", {
-                method: "POST",
-                headers,
-                body: JSON.stringify(result),
-              });
-            }),
-          );
+          const result = await request(base + "/poll" +
+            (created.capabilities?.longPoll ? `?wait=${Math.min(pollWaitMs, 10000)}` : ""),
+            { headers, signal: lifetime.signal });
+          if (Number.isFinite(result.expiresAt)) leaseUntil = result.expiresAt;
+          if (Date.now() >= leaseUntil) throw Object.assign(Error("Connection expired."), {terminal:true});
+          failures = 0;
+          await Promise.all((result.jobs ?? []).map(async job => {
+            let response;
+            try { response = await perform(job); }
+            catch { response = {id:job.id,status:502,headers:{"content-type":"application/json"},body:Buffer.from(JSON.stringify({error:"Local development service unavailable."})).toString("base64")}; }
+            await request(base + "/results", {method:"POST",headers,body:JSON.stringify(response)});
+          }));
+          if (!created.capabilities?.longPoll || pollWaitMs === 0) await pause(400);
         } catch (error) {
-          if (signal?.aborted || stopped) break;
-          if (!allowHttp)
-            process.stderr.write(
-              "Studio connection interrupted; retrying. Local development remains available.\n",
-            );
+          if (stopped || signal?.aborted) break;
+          if (error.terminal || error.status === 401 || error.status === 410) throw Error("Studio session expired or was revoked. Run studio connect again.");
+          warn();
+          await pause(Math.min(30000, 1000 * 2 ** Math.min(failures++, 5)));
         }
-        await new Promise((resolve) => setTimeout(resolve, 400));
       }
     } finally {
-      await fetch(base, {
-        method: "DELETE",
-        headers,
-        signal: AbortSignal.timeout(2000),
-      }).catch(() => {});
+      stop(); await updating;
+      signal?.removeEventListener("abort", stop);
+      await fetch(base, {method:"DELETE",headers,signal:AbortSignal.timeout(2000)}).catch(() => {});
     }
   })();
   return {
     ...created,
     done,
-    stop: () => {
-      stopped = true;
-    },
+    get expiresAt() { return leaseUntil; },
+    stop,
   };
 }
 export async function connectorCli(args) {
-  const option = (name) => {
-    const index = args.indexOf(name);
-    return index < 0 ? undefined : args[index + 1];
-  };
-  const controller = new AbortController();
-  for (const name of ["SIGINT", "SIGTERM"])
-    process.once(name, () => controller.abort());
-  let agent;
-  let local = option("--local") ?? process.env.STUDIO_LOCAL_ORIGIN;
-  if (!local) {
-    const { createConnectorAgent } = await import("./connector-agent.mjs");
-    agent = await createConnectorAgent(
-      option("--project") ?? process.env.STUDIO_PROJECT ?? "studio.config.mjs",
-    );
-    local = agent.url;
-  }
+  const option = name => { const index=args.indexOf(name);return index<0?undefined:args[index+1]; };
+  try { process.loadEnvFile(".env.studio.local"); } catch(error) { if(error.code!=="ENOENT")throw error; }
+  const studio=option("--studio");
+  if(!studio)throw Error("Provide your host: npx studio connect --studio https://studio.example.com");
+  const host=new URL(studio);
+  if(host.username||host.password||host.search||host.hash||host.pathname!=="/"||
+    (host.protocol!=="https:"&&!(args.includes("--allow-http")&&host.protocol==="http:"&&["localhost","127.0.0.1","[::1]"].includes(host.hostname))))
+    throw Error("Use a credential-free HTTPS Studio origin.");
+  const token=option("--token")??process.env.STUDIO_CONNECT_TOKEN;
+  if(!token)throw Error("Studio credentials are missing. Set STUDIO_CONNECT_TOKEN in your shell or .env.studio.local using the provisioning token supplied by your Studio host. Then run this command again.");
+  const {findConnectorConfig,verifyAppServer,startPreviewTunnel,openStudioBrowser}=await import("./connect-preview.mjs");
+  const {readFile}=await import("node:fs/promises");
+  const {join}=await import("node:path");
+  const controller=new AbortController();
+  const interrupt=()=>controller.abort();
+  for(const name of ["SIGINT","SIGTERM"])process.once(name,interrupt);
+  let agent,tunnel;
+  let local=option("--local")??process.env.STUDIO_LOCAL_ORIGIN;
   try {
-    const connection = await startConnector({
-      studio: option("--studio"),
-      token: option("--token") ?? process.env.STUDIO_CONNECT_TOKEN,
-      local,
-      previewUrl: option("--preview-url"),
-      nativeUrl: option("--native-url"),
-      allowHttp: args.includes("--allow-http"),
-      signal: controller.signal,
-      onConnected: async (created) => {
-        console.log(
-          `Open this private Studio pairing link:\n${created.editorUrl}\nConnection expires ${new Date(created.expiresAt).toISOString()}.`,
-        );
-        if (agent) {
-          const localSession = await (
-            await fetch(new URL("/__studio/dev/session", local))
-          ).json();
-          console.log(
-            `Local simulator link (works without LAN):\n${localSession.simulatorUrl}`,
-          );
-          if (args.includes("--simulator")) {
-            if (process.platform !== "darwin")
-              throw Error("The iOS simulator requires macOS.");
-            const { spawnSync } = await import("node:child_process");
-            const opened = spawnSync("xcrun", [
-              "simctl",
-              "openurl",
-              process.env.STUDIO_SIMULATOR_UDID ?? "booted",
-              localSession.simulatorUrl,
-            ]);
-            if (opened.status !== 0)
-              throw Error("Boot a simulator before using --simulator.");
-          }
+    if(!local){
+      const {createConnectorAgent}=await import("./connector-agent.mjs");
+      const file=option("--project")??process.env.STUDIO_PROJECT??await findConnectorConfig();
+      console.log("Checking project and generating Studio metadata…");
+      agent=await createConnectorAgent(file);local=agent.url;
+    }
+    let previewUrl=option("--preview-url"),nativeUrl=option("--native-url");
+    if(!previewUrl&&!args.includes("--native-only")){
+      let appUrl=option("--app-url")??agent?.project.connection?.developmentUrl??agent?.project.preview?.developmentUrl;
+      let expo=false;
+      if(agent){
+        try{const pkg=JSON.parse(await readFile(join(agent.project.discovery.root,"package.json"),"utf8"));expo=!!(pkg.dependencies?.expo??pkg.devDependencies?.expo);}catch{}
+      }
+      if(!appUrl&&expo)appUrl="http://127.0.0.1:8081/";
+      if(!appUrl)throw Error("No app development URL is configured. Start your app server and set connection.developmentUrl in the Studio config, or pass --app-url http://localhost:PORT. Use --native-only only when you intentionally do not need a web preview.");
+      console.log("Checking app development server…");
+      const origin=await verifyAppServer(appUrl,host.origin);
+      console.log("Creating HTTPS preview tunnel…");
+      tunnel=await startPreviewTunnel({url:origin,signal:controller.signal});
+      previewUrl=tunnel.url;
+      if(!nativeUrl&&expo)nativeUrl=previewUrl.replace(/^https:/,"exps:")+"--/";
+    }
+    if(option("--preview-url")) {
+      const target=new URL(previewUrl);
+      if(target.username||target.password||(target.protocol!=="https:"&&!(args.includes("--allow-http")&&target.protocol==="http:"&&["localhost","127.0.0.1","[::1]"].includes(target.hostname))))
+        throw Error("Use a credential-free HTTPS --preview-url.");
+      try { const response=await fetch(target,{signal:AbortSignal.any([controller.signal,AbortSignal.timeout(20000)])});
+        if(!response.ok||!(response.headers.get("content-type")??"").includes("text/html"))throw Error(`HTTP ${response.status}`);
+      } catch(error) { throw Error(`Preview URL is unavailable: ${error.message}. Start your app/tunnel and retry.`); }
+    }
+    if(controller.signal.aborted)return;
+    const connection=await startConnector({studio:host.origin,token,local,previewUrl,nativeUrl,
+      allowHttp:args.includes("--allow-http"),signal:controller.signal,
+      onConnected:async created=>{
+        const editor=new URL(created.editorUrl),capability=new URLSearchParams(editor.hash.slice(1)).get("studio");
+        const ready=await fetch(new URL(`/__studio/dev/${capability}/bootstrap`,host),{signal:AbortSignal.any([controller.signal,AbortSignal.timeout(20000)])});
+        if(!ready.ok)throw Error("Hosted workspace did not become ready. Check the Studio host and reconnect.");
+        console.log(`Ready — Studio is connected${previewUrl?" with a live web preview":" in native-only mode"}.\nThe session renews while this connector runs. Press Ctrl+C to disconnect.\nPrivate workspace:\n${created.editorUrl}`);
+        if(!args.includes("--no-open")){
+          try{await openStudioBrowser(created.editorUrl);}catch{console.log("Could not open your browser automatically. Open the private workspace link above.");}
         }
-      },
-    });
+        if(args.includes("--simulator")){
+          if(!agent||process.platform!=="darwin")throw Error("--simulator requires a standalone agent on macOS and a booted simulator.");
+          const localSession=await(await fetch(new URL("/__studio/dev/session",local))).json();
+          const {spawnSync}=await import("node:child_process");
+          if(spawnSync("xcrun",["simctl","openurl",process.env.STUDIO_SIMULATOR_UDID??"booted",localSession.simulatorUrl]).status!==0)
+            throw Error("Boot a simulator before using --simulator.");
+        }
+      }});
+    let tunnelFailed=false;
+    void tunnel?.exited.then(()=>{if(!controller.signal.aborted){tunnelFailed=true;controller.abort();}});
     await connection.done;
+    if(tunnelFailed)throw Error("The preview tunnel stopped. Check network access and run studio connect again, or supply --preview-url.");
   } finally {
-    await agent?.close();
+    controller.abort();await tunnel?.close();await agent?.close();
+    for(const name of ["SIGINT","SIGTERM"])process.removeListener(name,interrupt);
   }
 }

package/scripts/dev-channel.mjs

@@ -20,6 +20,7 @@ export async function createDevChannel(project, options = {}) {
     (await readDocument(project.state.authoring.snapshotFile));
   let document = mergeStudioDefaults(baseline, stored);
   if (project.content.validate(document).length) document = baseline;
+  let activeContractId = project.content.contractId;
   let revision = hash(document),
     writes = Promise.resolve();
   function hash(value) {
@@ -31,7 +32,7 @@ export async function createDevChannel(project, options = {}) {
     protocolVersion: 1,
     projectId: project.id,
     schemaVersion: project.content.schemaVersion,
-    contractId: project.content.contractId,
+    contractId: activeContractId,
     revision,
     publishedAt: new Date().toISOString(),
     document,
@@ -39,6 +40,7 @@ export async function createDevChannel(project, options = {}) {
   const handler = async (req, res) => {
     const route = new URL(req.url, "http://localhost").pathname;
     if (!route.startsWith("/__studio/dev/")) return false;
+    if (project.content.contractId !== activeContractId) await handler.refresh();
     const origin = `http://${req.headers.host}`;
     const send = (code, body) => {
       res.writeHead(code, {
@@ -66,7 +68,7 @@ export async function createDevChannel(project, options = {}) {
       return send(200, {
         projectId: project.id,
         schemaVersion: project.content.schemaVersion,
-        contractId: project.content.contractId,
+        contractId: activeContractId,
         endpoint,
         writeUrl: prefix + "/draft",
         nativeUrl,
@@ -81,7 +83,7 @@ export async function createDevChannel(project, options = {}) {
       return devices.handle(req, res, route.slice(prefix.length), send);
     if (route === prefix + "/content.json" && req.method === "GET") {
       const requested = new URL(req.url, origin).searchParams.get("contractId");
-      if (requested && requested !== project.content.contractId)
+      if (requested && requested !== activeContractId)
         return send(409, {
           error:
             "No compatible development content. Regenerate Studio and reload the app.",
@@ -121,6 +123,7 @@ export async function createDevChannel(project, options = {}) {
           await writeDocument(draftFile, next);
           document = next;
           revision = nextRevision;
+          activeContractId = project.content.contractId;
           hasDraft = true;
         });
         writes = task.catch(() => {});
@@ -137,14 +140,18 @@ export async function createDevChannel(project, options = {}) {
     }
     return send(404, { error: "Development session is unavailable." });
   };
-  handler.refresh = async () => {
-    await writes;
-    const latest = await readDocument(draftFile);
-    const baseline = project.content.defaults ?? await readDocument(project.state.authoring.snapshotFile);
-    const next = mergeStudioDefaults(baseline,latest);
-    if(project.content.validate(next).length)return false;
-    document=next;revision=hash(next);hasDraft=Object.keys(latest).length>0;
-    return true;
+  handler.refresh = () => {
+    const task = writes.then(async () => {
+      const latest = await readDocument(draftFile);
+      const baseline = project.content.defaults ?? await readDocument(project.state.authoring.snapshotFile);
+      const next = mergeStudioDefaults(baseline, latest);
+      if (project.content.validate(next).length) return false;
+      document = next; revision = hash(next); hasDraft = Object.keys(latest).length > 0;
+      activeContractId = project.content.contractId;
+      return true;
+    });
+    writes = task.catch(() => {});
+    return task;
   };
   return handler;
 }