@jxsuite/studio 6.0.0 → 6.1.1

package/src/panels/style-panel.ts

@@ -1471,13 +1471,32 @@ function buildEditor(
      match, and a menu that offers unmatchable states is a menu people stop reading. What the
      element already DECLARES and the active selector are unioned in after, so nothing an author has
      written can drop out of it. */
-  const selectorOptions = [
-    ...new Set([
-      ...selectorsForNode(node),
-      ...declaredSelectors,
-      ...(activeSelector ? [activeSelector] : []),
-    ]),
-  ];
+  /* In Project Styles the coordinate is a TAG PATH (`a`, `table th`) and its states nest under it
+     (`a :hover`). The menu offered the ROOT's states instead, and picking one replaced the tag, so
+     `:hover` styled the document element and a project had no way to write `a:hover` at all. Here
+     the states are the tag's own, spelled as the path they write. */
+  const stylebookPath =
+    stylebookSelector && isTagPath(stylebookSelector) ? stylebookSelector : null;
+  const stylebookLeaf = stylebookPath?.split(" ").at(-1) ?? null;
+  const stylebookDeclared = stylebookPath
+    ? Object.keys(resolveNestedTagStyle(style, stylebookPath)).filter((k) => isNestedSelector(k))
+    : [];
+  const selectorOptions = stylebookPath
+    ? [
+        ...new Set([
+          ...[...selectorsForNode({ tagName: stylebookLeaf ?? "div" }), ...stylebookDeclared].map(
+            (state) => `${stylebookPath} ${state}`,
+          ),
+          ...(activeSelector && activeSelector !== stylebookPath ? [activeSelector] : []),
+        ]),
+      ]
+    : [
+        ...new Set([
+          ...selectorsForNode(node),
+          ...declaredSelectors,
+          ...(activeSelector ? [activeSelector] : []),
+        ]),
+      ];
 
   // ── The Target Line (§6.2) ─────────────────────────────────────────────────
   const stylebookTag = stylebookTagOf(stylebookSelector);
@@ -1486,15 +1505,19 @@ function buildEditor(
   setTargetLine({
     segments: targetSegments(elementLabel, mediaTab, mediaNames.length > 0, schemeLayer),
     selector: {
-      value: activeSelector,
+      // The bare tag path IS the base rule in Project Styles, so it reads as the base entry.
+      value: stylebookPath && activeSelector === stylebookPath ? null : activeSelector,
       options: selectorOptions,
-      declared: declaredSelectors,
+      declared: stylebookPath
+        ? new Set(stylebookDeclared.map((state) => `${stylebookPath} ${state}`))
+        : declaredSelectors,
       onSelect: (value) => {
         const current = activeTab.value;
         if (!current) {
           return;
         }
-        current.session.ui.activeSelector = value;
+        // Clearing the state in Project Styles returns to the tag, never to the document root.
+        current.session.ui.activeSelector = value ?? stylebookPath;
         /* §6.2's own rule: a control that selects a rendering context has to change the rendering,
            or it is a control over a label. `:hover` gets away with not doing this because you can
            hover the element; `:popover-open` cannot, because a closed popover is not on the screen
@@ -1523,7 +1546,9 @@ function buildEditor(
             isNestedSelector(v.trim()) ? "" : 'A selector must start with ":", ".", "&" or "[".',
         }).then((value) => {
           if (value && activeTab.value) {
-            activeTab.value.session.ui.activeSelector = value.trim();
+            activeTab.value.session.ui.activeSelector = stylebookPath
+              ? `${stylebookPath} ${value.trim()}`
+              : value.trim();
           }
         });
       },

package/src/platforms/cloud.ts

@@ -48,6 +48,7 @@ import type {
   ReferencesResult,
   RenameResult,
   RepoInfo,
+  RepoProjects,
   StarterInfo,
   StudioPlatform,
 } from "../types";
@@ -56,12 +57,21 @@ import type { ReadFilesRequest, ReadFilesResult, UploadResult } from "@jxsuite/p
 import { reportActionRequired } from "../account/action-required";
 import { offeredActions, retryHint } from "../platform-errors";
 import { createReadBatcher } from "./read-batcher";
+import { normalizeProjectDir } from "../utils/project-dir";
 import type { BatchAnswer } from "./read-batcher";
 
+// Re-exported for the cloud shell and its tests, which spell folders through this entry.
+export { normalizeProjectDir } from "../utils/project-dir";
+
 export interface CloudProject {
   owner: string;
   repo: string;
   branch: string;
+  /**
+   * The folder holding the project's `project.json`, relative to the repository root and already
+   * normalized ({@link normalizeProjectDir}); absent or `""` when the project IS the repository.
+   */
+  dir?: string;
 }
 
 interface ProjectInfoWire {
@@ -213,12 +223,45 @@ async function reportRefusal(res: Response): Promise<void> {
   });
 }
 
-/** Editor URL for a project session (mirrors the shell's route). */
+/**
+ * The revision a session reads: the branch, then `:` and the project folder when there is one.
+ *
+ * Git's own `<rev>:<path>` notation, and unambiguous for the reason git can use it: `:` is one of
+ * the characters a ref name may never contain (git-check-ref-format), so the FIRST colon always
+ * ends the branch, however many slashes the branch or the folder holds.
+ */
+export function revisionSpec(project: CloudProject): string {
+  return project.dir ? `${project.branch}:${project.dir}` : project.branch;
+}
+
+/** Split a {@link revisionSpec} back into its branch and folder; null when either half is unusable. */
+function parseRevisionSpec(spec: string): { branch: string; dir?: string } | null {
+  const colon = spec.indexOf(":");
+  const branch = colon === -1 ? spec : spec.slice(0, colon);
+  const dir = colon === -1 ? "" : normalizeProjectDir(spec.slice(colon + 1));
+  if (!branch || dir === null) {
+    return null;
+  }
+  return dir ? { branch, dir } : { branch };
+}
+
+/**
+ * Editor URL for a project session (mirrors the shell's route):
+ * `/edit/<owner>/<repo>@<branch>[:<folder>]`. The branch is one encoded component, so its slashes
+ * travel as `%2F`; the folder keeps its slashes, so a subfolder project's address reads as the path
+ * it is.
+ */
 export function editUrl(project: CloudProject): string {
-  return `/edit/${project.owner}/${project.repo}@${encodeURIComponent(project.branch)}`;
+  const folder = project.dir
+    ? `:${project.dir
+        .split("/")
+        .map((segment) => encodeURIComponent(segment))
+        .join("/")}`
+    : "";
+  return `/edit/${project.owner}/${project.repo}@${encodeURIComponent(project.branch)}${folder}`;
 }
 
-/** Parse an /edit/:owner/:repo@:branch path (editUrl's inverse); null when it is not one. */
+/** Parse an /edit/:owner/:repo@:branch[:dir] path (editUrl's inverse); null when it is not one. */
 export function parseEditPath(pathname: string): CloudProject | null {
   /* Asset routers may normalize "@" to "%40", so decode the whole path first
      (branch slashes survive: `.+` spans them). */
@@ -232,22 +275,27 @@ export function parseEditPath(pathname: string): CloudProject | null {
   if (!match) {
     return null;
   }
-  const [, owner, repo, branch] = match;
-  if (!owner || !repo || !branch) {
+  const [, owner, repo, spec] = match;
+  const revision = spec ? parseRevisionSpec(spec) : null;
+  if (!owner || !repo || !revision) {
     return null;
   }
-  return { owner, repo, branch };
+  return { owner, repo, ...revision };
 }
 
-/** Gateway base path for a project session. */
+/**
+ * Gateway base path for a project session. The revision spec — branch and folder — is ONE encoded
+ * segment, so the gateway's route shape is the same for a subfolder project as for a repository,
+ * and the folder's slashes cannot be mistaken for the session's own sub-path.
+ */
 export function sessionBase(project: CloudProject): string {
-  const { owner, repo, branch } = project;
-  return `/api/v1/p/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/${encodeURIComponent(branch)}/studio`;
+  const { owner, repo } = project;
+  return `/api/v1/p/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}/${encodeURIComponent(revisionSpec(project))}/studio`;
 }
 
-/** Catalogue/recents root key for a project: "owner/repo@branch". */
+/** Catalogue/recents root key for a project: "owner/repo@branch", plus ":dir" for a subfolder. */
 export function projectRootKey(project: CloudProject): string {
-  return `${project.owner}/${project.repo}@${project.branch}`;
+  return `${project.owner}/${project.repo}@${revisionSpec(project)}`;
 }
 
 /**
@@ -559,17 +607,18 @@ function awaitAction(popup: Window): Promise<ActionOutcome> {
   });
 }
 
-/** Parse an "owner/repo@branch" root key; null when malformed. */
+/** Parse an "owner/repo@branch[:dir]" root key; null when malformed. */
 export function parseRootKey(root: string): CloudProject | null {
   const match = /^([^/@]+)\/([^/@]+)@(.+)$/.exec(root);
   if (!match) {
     return null;
   }
-  const [, owner, repo, branch] = match;
-  if (!owner || !repo || !branch) {
+  const [, owner, repo, spec] = match;
+  const revision = spec ? parseRevisionSpec(spec) : null;
+  if (!owner || !repo || !revision) {
     return null;
   }
-  return { owner, repo, branch };
+  return { owner, repo, ...revision };
 }
 
 /** Every project this account can open, straight off the wire; [] when the catalogue is unreachable. */
@@ -1558,13 +1607,40 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
       }));
     },
 
-    /** Adopt an existing repo as a Jx project; resolves to its catalogue root key. */
-    async importProject(opts: { owner: string; name: string }) {
+    /**
+     * The folders of a repository that hold a project.json, read from its default branch. The
+     * platform drops vendored folders and other tools' `project.json` (Nx's), and says when the
+     * repository was too large to list in full.
+     */
+    async listRepoProjects(repo: { owner: string; name: string }): Promise<RepoProjects> {
+      const res = await fetch(
+        `/api/v1/repos/${encodeURIComponent(repo.owner)}/${encodeURIComponent(repo.name)}/projects`,
+        { credentials: "include" },
+      );
+      const found = await okJson<RepoProjects>(res, "Failed to look for projects");
+      /* Canonical on the way in, so a location the reader picks is spelled the way the root key,
+         the editor URL and the session will spell it; anything that climbs out is not offered. */
+      const locations: RepoProjects["locations"] = [];
+      for (const location of found.locations) {
+        const dir = normalizeProjectDir(location.dir);
+        if (dir !== null) {
+          locations.push(location.name ? { dir, name: location.name } : { dir });
+        }
+      }
+      return { branch: found.branch, locations, truncated: found.truncated === true };
+    },
+
+    /** Adopt an existing repo (or one folder of it) as a Jx project; resolves to its root key. */
+    async importProject(opts: { owner: string; name: string; dir?: string }) {
+      const dir = normalizeProjectDir(opts.dir ?? "");
+      if (dir === null) {
+        throw new Error("The project folder must stay inside the repository.");
+      }
       const res = await fetch("/api/v1/projects/import", {
         method: "POST",
         credentials: "include",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify(opts),
+        body: JSON.stringify({ owner: opts.owner, name: opts.name, ...(dir ? { dir } : {}) }),
       });
       const imported = await okJson<{ owner: string; name: string; defaultBranch: string }>(
         res,
@@ -1575,6 +1651,7 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
           owner: imported.owner,
           repo: imported.name,
           branch: imported.defaultBranch,
+          ...(dir ? { dir } : {}),
         }),
       };
     },

package/src/platforms/devserver.ts

@@ -98,6 +98,50 @@ export function createDevServerPlatform() {
    */
   let _collabConnection: Promise<WsCollabConnection> | null = null;
 
+  /**
+   * Bind the server to `root` — the binding its rootless routes and its static fallback (every
+   * media thumbnail, every canvas image) resolve against.
+   *
+   * **The binding is one per SERVER, not per tab.** So an empty root posts nothing: a Studio tab
+   * opened with no project used to post `{ root: "" }` at boot, which unbound the server for every
+   * other tab and turned their images into 404s. And a tab re-claims it (see
+   * {@link reclaimBinding}) whenever it could have been taken.
+   */
+  async function postActivate(root: string): Promise<void> {
+    if (!root) {
+      return;
+    }
+    const res = await fetch("/__studio/activate", {
+      body: JSON.stringify({ root }),
+      headers: { "Content-Type": "application/json" },
+      method: "POST",
+    });
+    if (!res.ok) {
+      const body = (await readJson<ErrorBody>(res).catch(() => ({}))) as ErrorBody;
+      throw new Error(
+        `Could not open ${root}: ${problemDetail(body) ?? `activation failed (${res.status})`}`,
+      );
+    }
+  }
+
+  /**
+   * Re-bind the server to this tab's project. Two events can take the binding away without this tab
+   * hearing of it: another Studio tab activating ITS project, and a restarted `bun run dev`, which
+   * comes back bound to nothing. So a tab re-claims it when the author comes back to it (focus) and
+   * when the reload stream reconnects (a restart). Only a tab with a project claims anything.
+   */
+  function reclaimBinding(): void {
+    if (!_projectRoot) {
+      return;
+    }
+    _activation = postActivate(_projectRoot).catch((error: unknown) => {
+      console.error("Project re-activation failed:", error);
+    });
+  }
+  if (typeof window !== "undefined") {
+    window.addEventListener("focus", reclaimBinding);
+  }
+
   /**
    * Prefix a project-relative path with the active project root for server API calls.
    *
@@ -162,18 +206,7 @@ export function createDevServerPlatform() {
      * @param {string} [root]
      */
     async activate(root?: string) {
-      const r = root ?? _projectRoot;
-      const res = await fetch("/__studio/activate", {
-        body: JSON.stringify({ root: r }),
-        headers: { "Content-Type": "application/json" },
-        method: "POST",
-      });
-      if (!res.ok) {
-        const body = (await readJson<ErrorBody>(res).catch(() => ({}))) as ErrorBody;
-        throw new Error(
-          `Could not open ${r}: ${problemDetail(body) ?? `activation failed (${res.status})`}`,
-        );
-      }
+      await postActivate(root ?? _projectRoot);
     },
 
     // ─── Project opening ──────────────────────────────────────────────────
@@ -514,6 +547,8 @@ export function createDevServerPlatform() {
       es.addEventListener("open", () => {
         opens += 1;
         if (opens > 1) {
+          // A reconnect is usually a restarted server, which comes back bound to no project.
+          reclaimBinding();
           options?.onResync?.("reconnect");
         }
       });

package/src/publish/pages-service.ts

@@ -36,6 +36,12 @@ export interface ConnectOptions {
   productionBranch: string;
   owner: string;
   repo: string;
+  /**
+   * The folder of the repository the project lives in, when it is not the root (a cloud project
+   * opened from a subfolder). Pages builds there, so `bunx jx build` finds that project's
+   * `project.json` and `dist` is that project's output.
+   */
+  rootDir?: string;
 }
 
 /** True when the active platform can reach the Cloudflare API. */
@@ -106,6 +112,7 @@ export async function createPagesProject(opts: ConnectOptions): Promise<PagesPro
       build_config: {
         build_command: "bunx jx build",
         destination_dir: "dist",
+        ...(opts.rootDir ? { root_dir: opts.rootDir } : {}),
       },
       source: {
         type: "github",

package/src/publish/publish-panel.ts

@@ -19,12 +19,12 @@
  * HTML, in the accessibility tree and in every DOM dump. It is gone, and the document is now the
  * thing that makes it impossible rather than the thing that remembers not to — the field binds no
  * `value` at all, and the draft lives in the adapter's closure until {@link saveToken} reads it. A
- * stored token is reported as *stored*, the field is only ever drawn for a REPLACEMENT the reader
+ * stored token is reported as _stored_, the field is only ever drawn for a REPLACEMENT the reader
  * asked for, and revoking lives where every other credential's does — Preferences › Accounts
  * (`studio.md` §15 rule 1: a surface never prints the secret it describes).
  *
- * @docs studio/publish/cloudflare
  * @license MIT
+ * @docs studio/publish/cloudflare
  */
 
 import type { DeployConfig, ProjectConfig } from "@jxsuite/schema/types";
@@ -36,6 +36,7 @@ import { resetModelCache } from "../services/ai-models";
 import { projectState } from "../store";
 import type { CfConnection } from "../types";
 import { layerHost } from "../ui/layers";
+import { normalizeProjectDir } from "../utils/project-dir";
 import { openPublishSurface } from "../surfaces/publish";
 import type { PublishForm, PublishSurfaceHandle, PublishView } from "../surfaces/publish";
 import type { CfAccount, PagesDeploymentInfo } from "./pages-service";
@@ -82,6 +83,17 @@ function prefillRepo(): { owner: string; repo: string } {
   return match ? { owner: match[1]!, repo: match[2]! } : { owner: "", repo: "" };
 }
 
+/**
+ * The repository folder a cloud project lives in ("owner/repo@branch:sites/blog"), or "" for one
+ * that is the whole repository and for every non-cloud root. Not a form field: the folder is the
+ * project's identity rather than a choice, and a Pages project that built anywhere else would build
+ * a different project, or none.
+ */
+function projectFolder(): string {
+  const spec = /^[\w.-]+\/[\w.-]+@[^:]+:(.+)$/.exec(getPlatform().projectRoot)?.[1] ?? "";
+  return normalizeProjectDir(spec) ?? "";
+}
+
 /** The connected Pages project, as the surface takes it: strings, never a config object. */
 function deployView(): { projectName: string; productionUrl: string } | null {
   const deploy: DeployConfig | undefined = currentDeploy();
@@ -257,12 +269,14 @@ async function submitConnect(): Promise<void> {
   _error = "";
   paint();
   try {
+    const rootDir = projectFolder();
     const deploy = await connectDeploy(config, {
       accountId: _form.accountId,
       owner: _form.owner,
       productionBranch: _form.branch || "main",
       projectName: _form.projectName,
       repo: _form.repo,
+      ...(rootDir ? { rootDir } : {}),
     });
     _deployment = await latestDeployment(deploy).catch(() => null);
   } catch (error) {

package/src/studio.ts

@@ -200,7 +200,8 @@ import * as chatPanelMod from "./panels/chat-panel";
 import { setProjectAdopter } from "./services/project-adoption";
 import { setImportHandoff } from "./services/import-seed";
 import { watchConnection } from "./services/connection";
-import { tabBufferUnsaved } from "./services/monaco-buffer";
+import { commitTabBuffers, tabBufferUnsaved } from "./services/monaco-buffer";
+import { clearTyping } from "./tabs/typing";
 import * as leftPanelMod from "./panels/left-panel";
 import * as tabStrip from "./panels/tab-strip";
 import * as paneContext from "./panels/pane-context";
@@ -1492,7 +1493,18 @@ registerStudioCommands(
     // Whether the bytes landed, and a hook that neither supplies one nor reads the answer must not
     // Silently forward its own first argument as the tab to save.
     saveDocument: async () => {
-      await saveFile();
+      const tab = activeTab.value;
+      if (!tab) {
+        return;
+      }
+      // What a source buffer holds goes into the document first, or ⌘S inside the commit's
+      // Debounce would save the text from before the last keystrokes.
+      await commitTabBuffers(tab);
+      await saveFile(tab);
+      // Text that would not parse is still only in the buffer, so it is still unsaved.
+      if (!tabBufferUnsaved(tab)) {
+        clearTyping(tab.id);
+      }
     },
   },
   stageContext,