@jxsuite/studio 5.3.0 → 5.4.0

package/src/github/github-auth.ts

@@ -46,6 +46,13 @@
  * on the desktop it is in the launcher's `0600` credential store and this module holds it only in
  * memory for the session. `settings/preferences-accounts.ts` lists it as _stored or not_ and is the
  * only place it can be revoked (`studio.md` §15 rule 1).
+ *
+ * The credential STATE (whether one exists, where, how to clear it) lives in
+ * `github-auth-status.ts` and is re-exported here. This module keeps only the sign-in FLOW, which
+ * is the half that needs `notify` and the device-flow dialog surface — a launcher's PAL-init bundle
+ * wants the state without ever wanting the flow, and importing this whole file for
+ * `hydrateGithubToken` alone used to cost it a second copy of Lit's runtime
+ * (`github-auth-status.ts`'s own header has the full account).
  */
 
 import { errorMessage } from "@jxsuite/schema/parse";
@@ -53,74 +60,18 @@ import { notify } from "../services/notify";
 import { layerHost } from "../ui/layers";
 import { openGithubAuthSurface } from "../surfaces/github-auth";
 import type { GithubAuthSurfaceHandle } from "../surfaces/github-auth";
+import { getGithubToken, nativeAuth, setNativeToken, STORAGE_KEY } from "./github-auth-status";
 
-const CLIENT_ID = "Ov23liYVlMFpgjOEPXJH";
-const STORAGE_KEY = "jx_github_token";
-
-/**
- * The desktop launcher's RFC 8252 sign-in, when this build is running inside one.
- *
- * Launcher-only, like `updater` and `windowControls`, and reached the same way — a loopback
- * redirect needs a loopback server, which a page in a browser does not have.
- */
-interface NativeGithubAuth {
-  signIn: (force?: boolean) => Promise<{ token: string }>;
-  signOut: () => Promise<{ ok: boolean }>;
-  status: () => Promise<{ stored: boolean }>;
-}
-
-function nativeAuth(): NativeGithubAuth | null {
-  return (
-    (globalThis as unknown as { __jxPlatform?: { githubAuth?: NativeGithubAuth } }).__jxPlatform
-      ?.githubAuth ?? null
-  );
-}
-
-/**
- * The token the desktop store handed us this session.
- *
- * On the desktop the token at rest is a `0600` file in the user's config directory, **not**
- * `localStorage` — so it is not readable by script in the webview between sessions, and it does not
- * survive in a place a stray extension or a copied profile can reach. Holding it in a module
- * variable is what keeps {@link getGithubToken} synchronous for its callers.
- */
-let nativeToken: string | null = null;
-
-/** Whether the desktop store holds a token, as of the last time it was asked. */
-let nativeStored = false;
-
-/**
- * Record that the desktop's credential store does (or does not) hold a token.
- *
- * The launcher calls this once at startup. It carries a **boolean, not the token**: the accounts
- * pane only needs to know whether one exists, and handing the webview a credential it has not been
- * asked to use is the exposure the 0600 store exists to remove. When a sign-in does happen the
- * token arrives through {@link authenticateGithub} and lives in memory for that session.
- *
- * @param {boolean} stored
- */
-export function hydrateGithubToken(stored: boolean): void {
-  nativeStored = stored;
-}
-
-/**
- * Whether a GitHub credential exists, wherever it lives.
- *
- * Separate from {@link getGithubToken} because the two questions genuinely differ on the desktop: a
- * token can be stored on disk and not yet in this session's memory, and the accounts pane asks
- * "signed in?" while rendering — synchronously — where an API caller asks for the credential itself
- * and can await it.
- *
- * @returns {boolean}
- */
-export function githubTokenStored(): boolean {
-  return nativeToken !== null || nativeStored || localStorage.getItem(STORAGE_KEY) !== null;
-}
+// Every other caller in Studio still reaches these through this module.
+export {
+  clearGithubToken,
+  getGithubToken,
+  githubTokenLocation,
+  githubTokenStored,
+  hydrateGithubToken,
+} from "./github-auth-status";
 
-/** Where the credential this build would use actually lives, for text that says so. */
-export function githubTokenLocation(): "desktop" | "browser" {
-  return nativeAuth() ? "desktop" : "browser";
-}
+const CLIENT_ID = "Ov23liYVlMFpgjOEPXJH";
 
 /** One key for the whole sign-in, so a second attempt REPLACES the first report. */
 const NOTIFY_KEY = "github.auth";
@@ -156,21 +107,6 @@ interface TokenResponse {
   error?: string;
 }
 
-export function getGithubToken() {
-  return nativeToken ?? localStorage.getItem(STORAGE_KEY);
-}
-
-export function clearGithubToken() {
-  nativeToken = null;
-  nativeStored = false;
-  localStorage.removeItem(STORAGE_KEY);
-  // Fire-and-forget: the accounts pane's revoke is synchronous, and a store that failed to forget
-  // The token is not something the user can act on from there.
-  void nativeAuth()
-    ?.signOut()
-    .catch(() => {});
-}
-
 /** The request never completed — a Problem, with the one sentence that covers both causes. */
 function reportUnreachable(error: unknown): void {
   notify.error("Could not reach GitHub to sign in.", {
@@ -241,7 +177,7 @@ export async function authenticateGithub() {
   if (native) {
     try {
       const { token } = await native.signIn();
-      nativeToken = token;
+      setNativeToken(token);
       return token;
     } catch (error) {
       reportRefused("GitHub sign-in was not completed.", errorMessage(error));

package/src/github/github-publish.ts

@@ -3,18 +3,19 @@
  * Create a GitHub repository for a local project, add it as `origin`, and push.
  *
  * **This is not publishing, and it used to say it was.** Two unrelated operations shared the verb
- * (plan §9.5): this one creates a git repository, and `publish/publish-panel.ts` connects a hosting
- * provider that then builds the site. A user who wanted the second and found the first got a GitHub
- * repository and no site, and a user who wanted the first read "Publish to GitHub" and reasonably
- * expected a URL. The function, the dialog headline, the activity title and the notification source
- * now all say _Create GitHub Repository_; `Publish:` belongs to `publish/publish-commands.ts`.
+ * (`docs/studio/publish.md`): this one creates a git repository, and `publish/publish-panel.ts`
+ * connects a hosting provider that then builds the site. A user who wanted the second and found the
+ * first got a GitHub repository and no site, and a user who wanted the first read "Publish to
+ * GitHub" and reasonably expected a URL. The function, the dialog headline, the activity title and
+ * the notification source now all say _Create GitHub Repository_; `Publish:` belongs to
+ * `publish/publish-commands.ts`.
  *
  * **It is an Activity, not three toasts.** Three `notify.info` lines sharing one key replaced each
  * other in a corner while a multi-second, three-request, partially-committing operation ran with no
  * log and no cancel — and its middle step (`gitAddRemote`) had no error path at all, so a remote
  * that already existed failed the push with a message about pushing. `beginActivity` gives it the
  * ordered steps, the captured log, and `fail()`, which raises the Problem the failure needs and
- * carries the log as its detail (§7.3). The caller therefore never also notifies.
+ * carries the log as its detail (§16.4). The caller therefore never also notifies.
  *
  * **The dialog is a document.** `surfaces/github-publish.json` collects the name, the description
  * and the visibility; this module keeps the token, the requests and the activity. What it used to

package/src/grid/cell-editors.ts

@@ -40,13 +40,14 @@
  * registry keyed to nodes the engine has already thrown away — and would repaint asynchronously
  * while the reader scrolls.
  *
- * So the boundary is the cell, and it is the same boundary §9.4 already draws around Tabulator: the
- * engine is an island, and this file is the inside of it. The two kinds whose picker is bigger than
- * a cell escaped it by leaving the cell entirely, and that is the shape any future conversion has
- * to take — a document ANCHORED at the cell, not mounted in it. What would actually unblock the
- * rest is a synchronous mount path in the runtime (a document rendered into a detached host with
- * the kit already registered, no awaits), at which point 1 and 2 dissolve and only the formatter's
- * lifetime problem is left, which needs a teardown hook Tabulator does not have.
+ * So the boundary is the cell, and it is the same boundary studio-ui-guidelines.md §9.4 already
+ * draws around Tabulator: the engine is an island, and this file is the inside of it. The two kinds
+ * whose picker is bigger than a cell escaped it by leaving the cell entirely, and that is the shape
+ * any future conversion has to take — a document ANCHORED at the cell, not mounted in it. What
+ * would actually unblock the rest is a synchronous mount path in the runtime (a document rendered
+ * into a detached host with the kit already registered, no awaits), at which point 1 and 2 dissolve
+ * and only the formatter's lifetime problem is left, which needs a teardown hook Tabulator does not
+ * have.
  */
 import { html, render } from "lit-html";
 /* The two cell editors below are re-rendered while they are open — the pill editor calls its own

package/src/grid/grid-layout.ts

@@ -5,7 +5,7 @@
  * the grid shipped; a saved view is the same record with three more facets and a name, written to
  * the same key. The alternative — a second `jx-grid-views:` store beside this one — is how a grid
  * ends up with a column order that a view cannot capture and a view that a resize does not update,
- * which is the class of bug plan §12 P7.2 asks this item to avoid by construction.
+ * which is the class of bug saved views (site-architecture.md §7.2) must avoid by construction.
  *
  * **The working layout is the truth; a view is a copy of it.** Every control writes the working
  * layout (`saveGridLayout`), so a grid remembers how you left it whether or not you ever name a

package/src/grid/grid-open.ts

@@ -250,8 +250,8 @@ export async function openGridSourcePicker(): Promise<void> {
  * `collection.editInGrid` used to be a press on the file tree's context-menu row, matched by the
  * item's rendered label ("Edit Collection in Grid") through an XPath — so the shot that used it
  * also had to open the menu first, and renaming the row broke both steps. Naming the COLLECTION
- * instead of the control is what plan §13's R1 asks for: the menu row and the command are the same
- * action, and only one of them is addressable.
+ * instead of the control is what the shot contract's R1 (`scripts/screenshots/README.md`) asks for:
+ * the menu row and the command are the same action, and only one of them is addressable.
  *
  * Both refuse a source the project does not declare. `data.openGrid` is additionally gated on the
  * platform serving the data routes (`capability.dataRows`), so on a build without them the command
@@ -272,8 +272,8 @@ export function gridCommands(): AnyCommand[] {
       group: "5_data",
       requires: "a project that declares content collections",
       when: (ctx) => ctx.project.open,
-      /* No `aiTool`, by §12.4's first deletion rule: this opens a surface for a person; the grid is
-         not a tool surface. */
+      /* No `aiTool`, by studio-ui-guidelines.md §12.4's first deletion rule: this opens a surface
+         for a person; the grid is not a tool surface. */
       run: (_commandCtx, args) => {
         const name = stringArg("collection.editInGrid", args, "name");
         const declared = collectionDirs().map((c) => c.name);
@@ -308,7 +308,8 @@ export function gridCommands(): AnyCommand[] {
       requires: "a platform that serves the data routes",
       when: (ctx) => ctx.project.open,
       enablement: (ctx) => ctx.capability.dataRows,
-      /* No `aiTool`, by §12.4's first deletion rule: this opens a surface for a person. */
+      /* No `aiTool`, by studio-ui-guidelines.md §12.4's first deletion rule: this opens a surface
+         for a person. */
       run: (_commandCtx, args) => {
         const table = stringArg("data.openGrid", args, "table");
         openConnectorGrid(optionalStringArg("data.openGrid", args, "connection"), table);

package/src/grid/grid-panel.ts

@@ -24,13 +24,13 @@
  *   palette, and the host node arriving all reach the surface through
  *   {@link ActiveGridPanel.bump}.
  *
- * **The panel owns the view state** (plan §12 P7.2). Saved views persist through `grid-layout.ts` —
- * one store, the grid id as its key, so "per collection" needs no code — and this module is what
- * drives them onto the four surfaces they touch: the engine (column order, width and visibility,
- * applied by a REBUILD, which is cheap because the data never leaves the controller), the
- * controller (sort and grouping, which are row order and belong to the data), and the surface's own
- * filter box. Applying a view is therefore one function with one order of operations, not five
- * controls that each half-remember what the others did.
+ * **The panel owns the view state** (saved views, site-architecture.md §7.2). Saved views persist
+ * through `grid-layout.ts` — one store, the grid id as its key, so "per collection" needs no code —
+ * and this module is what drives them onto the four surfaces they touch: the engine (column order,
+ * width and visibility, applied by a REBUILD, which is cheap because the data never leaves the
+ * controller), the controller (sort and grouping, which are row order and belong to the data), and
+ * the surface's own filter box. Applying a view is therefore one function with one order of
+ * operations, not five controls that each half-remember what the others did.
  */
 import { effect, effectScope, reactive } from "../reactivity";
 import { showConfirmDialog, showPromptDialog } from "../ui/layers";
@@ -259,9 +259,9 @@ function projectViews(controller: GridController, at: { x: number; y: number }):
  * The View panel: saved views, then the four facets one of them is made of.
  *
  * One control rather than four, because the chrome budget is a cap on named things in the toolbar
- * (plan §2, principle 9) and these four are only ever adjusted together. Each edit writes the
- * working layout and applies immediately — there is no Apply button, so there is no state in which
- * the panel shows something the grid is not already doing.
+ * (studio-ui-guidelines.md §12.2) and these four are only ever adjusted together. Each edit writes
+ * the working layout and applies immediately — there is no Apply button, so there is no state in
+ * which the panel shows something the grid is not already doing.
  */
 function openViewPopover(
   controller: GridController,
@@ -727,7 +727,8 @@ export function gridViewCommands(): AnyCommand[] {
       requires: "a grid on screen",
       when: (ctx) => ctx.project.open,
       enablement: () => activeGridSurface() !== null,
-      /* No `aiTool`, by §12.4's second deletion rule: it prompts for a name. */
+      /* No `aiTool`, by studio-ui-guidelines.md §12.4's second deletion rule: it prompts for a
+         name. */
       run: async () => {
         const { controller, panel } = requireSurface("grid.saveView");
         await promptSaveView(controller, panel);
@@ -744,7 +745,7 @@ export function gridViewCommands(): AnyCommand[] {
       requires: "a grid on screen",
       when: (ctx) => ctx.project.open,
       enablement: () => activeGridSurface() !== null,
-      /* No `aiTool`, by §12.4's first deletion rule: chrome. */
+      /* No `aiTool`, by studio-ui-guidelines.md §12.4's first deletion rule: chrome. */
       run: (_ctx, args) => {
         const { gridId, name } = viewNameArg("grid.applyView", args);
         const { panel } = requireSurface("grid.applyView");

package/src/grid/redirects-grid.ts

@@ -1,7 +1,7 @@
 /// <reference lib="dom" />
 /**
- * Redirects as a {@link GridSource} — the editor §11.4 asks for, over the table the grid already
- * is.
+ * Redirects as a {@link GridSource} — the editor site-architecture.md §11.4 asks for, over the
+ * table the grid already is.
  *
  * `project.json`'s `redirects` map is tabular, so it does not need a bespoke editor: it needs the
  * one Studio already has. Columns, inline editing, add/delete rows, undo, the dirty dot, ⌘S,
@@ -13,8 +13,8 @@
  *
  * **Every write goes through the one door.** Rows commit with {@link commitProjectConfig}, so a
  * redirect edit is a transaction on the `project.json` document with the same undo, the same
- * serialisation and the same refusal-with-a-Problem as every other configuration write (P6.1). This
- * module never touches `platform.writeFile`.
+ * serialisation and the same refusal-with-a-Problem as every other configuration write (§17.1).
+ * This module never touches `platform.writeFile`.
  *
  * **Row keys are positions.** A redirect's identity in `project.json` IS its source string, and the
  * source is the cell an author most often edits — so keying rows by it would turn every rename into
@@ -403,9 +403,10 @@ export async function openRedirectsGrid(): Promise<GridController> {
  * The paste box.
  *
  * It is `showPromptDialog` with a multiline field, not a dialog of its own. An import is one value
- * the author pastes and one answer they give, which is what that flow already is (§12.5); what it
- * needed was a field tall enough to read the value back in, and a monospaced one, because both
- * formats are column-aligned in the file they were copied out of.
+ * the author pastes and one answer they give, which is what that flow already is
+ * (studio-ui-guidelines.md §12.5); what it needed was a field tall enough to read the value back
+ * in, and a monospaced one, because both formats are column-aligned in the file they were copied
+ * out of.
  */
 export function promptRedirectImport(): Promise<string | null> {
   return showPromptDialog("Import Redirects", {
@@ -503,8 +504,9 @@ export function redirectsCommands(): AnyCommand[] {
       group: "5_data",
       requires: "an open project",
       when: (ctx) => ctx.project.open,
-      /* No `aiTool`, by §12.4's first deletion rule: this opens a surface for a person, and the
-         check it runs on the way is `validate_redirects`, which is projected. */
+      /* No `aiTool`, by studio-ui-guidelines.md §12.4's first deletion rule: this opens a surface
+         for a person, and the check it runs on the way is `validate_redirects`, which is
+         projected. */
       run: async () => {
         await openRedirectsGrid();
         reportRedirectProblems(rulesFromConfig(currentConfig()), await projectRoutes());
@@ -568,8 +570,9 @@ export function redirectsCommands(): AnyCommand[] {
       group: "5_data",
       requires: "an open project",
       when: (ctx) => ctx.project.open,
-      /* No `aiTool`, by §12.4's second deletion rule: without `text`, `run` awaits a paste dialog
-         the person answers, and the staged rows are a surface for that person to review. */
+      /* No `aiTool`, by studio-ui-guidelines.md §12.4's second deletion rule: without `text`, `run`
+         awaits a paste dialog the person answers, and the staged rows are a surface for that person
+         to review. */
       run: async (_ctx, args) => {
         const given = optionalStringArg("redirects.import", args, "text");
         const text = given ?? (await promptRedirectImport());

package/src/grid/redirects.ts

@@ -17,7 +17,8 @@
  * - **Shadow** — the project has a real route the rule's source covers. On a host that serves static
  *   assets before consulting `_redirects` (Netlify, Cloudflare Pages) the page wins and the rule is
  *   dead config; in `dist/` the compiler's own meta-refresh file overwrites the page and warns
- *   (§11.1). Two hosts, two answers, and neither is what the author intended by writing both.
+ *   (site-architecture.md §11.1). Two hosts, two answers, and neither is what the author intended
+ *   by writing both.
  *
  * **What is deliberately NOT decided.** A destination containing `:param` or `*` is not followed:
  * its concrete target depends on the request, so calling it a chain would be a guess. Nothing is
@@ -67,7 +68,10 @@ export function normalizePath(path: string): string {
   return trimmed.length > 1 && trimmed.endsWith("/") ? trimmed.slice(0, -1) : trimmed;
 }
 
-/** Whether a path is a URLPattern rather than a literal — `:param` or `*` (§11.2). */
+/**
+ * Whether a path is a URLPattern (site-architecture.md §11.2) rather than a literal — `:param` or
+ * `*`.
+ */
 export function isPattern(path: string): boolean {
   return path.includes(":") || path.includes("*");
 }
@@ -80,9 +84,10 @@ export function isExternal(path: string): boolean {
 /**
  * Whether `path` is covered by `pattern`.
  *
- * URLPattern-lite over pathname segments, which is all §11.2 uses: `:name` matches exactly one
- * non-empty segment and `*` matches the rest, including nothing. Enough to answer "does this rule
- * ever fire for that request", which is the only question chain, loop and shadow ask.
+ * URLPattern-lite over pathname segments, which is all site-architecture.md §11.2 uses: `:name`
+ * matches exactly one non-empty segment and `*` matches the rest, including nothing. Enough to
+ * answer "does this rule ever fire for that request", which is the only question chain, loop and
+ * shadow ask.
  */
 export function matchesPattern(pattern: string, path: string): boolean {
   const p = normalizePath(pattern).split("/");

package/src/grid/sources/content-source.ts

@@ -12,12 +12,12 @@
  * Collections type their columns from the content-type schema (plus inferred extras found in the
  * data); the pages grid is fully inference-driven.
  *
- * **A collection listing obeys the draft perspective (§7.6).** `content/draft-state.ts` owns both
- * the one flag and the one definition of what a draft is, and this source calls it rather than
- * testing `draft === true` itself — which is what makes "including drafts" mean the same thing here
- * as it does on the tab chip. It can, because that module imports nothing but `reactivity`: the
- * richer `content/entry-model.ts` asks THIS file where a collection's entries live, so an edge back
- * to it would be the cycle `import/no-cycle` rejects.
+ * **A collection listing obeys the draft perspective (site-architecture.md §7.6).**
+ * `content/draft-state.ts` owns both the one flag and the one definition of what a draft is, and
+ * this source calls it rather than testing `draft === true` itself — which is what makes "including
+ * drafts" mean the same thing here as it does on the tab chip. It can, because that module imports
+ * nothing but `reactivity`: the richer `content/entry-model.ts` asks THIS file where a collection's
+ * entries live, so an edge back to it would be the cycle `import/no-cycle` rejects.
  */
 import { getPlatform } from "../../platform";
 import { projectState } from "../../store";
@@ -207,9 +207,10 @@ interface EntryFileSourceOptions {
   /** Inferred columns to front-load, in order (e.g. title/description for pages). */
   priorityFields?: string[];
   /**
-   * Whether this listing is subject to the draft perspective (§7.6) — collections are, the pages
-   * tree is not. A draft is a property of a content ENTRY: a page carrying `draft: true` would
-   * vanish from the only tree that lists it, with no collection schema to explain why.
+   * Whether this listing is subject to the draft perspective (site-architecture.md §7.6) —
+   * collections are, the pages tree is not. A draft is a property of a content ENTRY: a page
+   * carrying `draft: true` would vanish from the only tree that lists it, with no collection schema
+   * to explain why.
    */
   drafts?: boolean;
 }

package/src/hosting/document.ts

@@ -24,6 +24,20 @@ import type { AssetBase } from "./layout";
 /** The default base: the tree served at the document's own directory, in the package's own shape. */
 export const IN_PLACE: AssetBase = { mode: "nested", prefix: "./" };
 
+/**
+ * The marker a document carries when it declares boot modules: `<meta name="jx-boot"
+ * content="launcher">`.
+ *
+ * It is how the studio entry tells "nobody registered an adapter because this is the dev server"
+ * from "somebody was supposed to and did not". The two looked identical from inside the bundle, and
+ * Studio answered both with the dev-server adapter, so a launcher whose boot script 404'd or failed
+ * to parse got a window that drew, fetched `/__studio/*` from an origin with nothing behind it, and
+ * failed on the first click. A meta rather than a script global because it is in the markup before
+ * any script runs, and so survives exactly the failures it exists to report: a boot module that
+ * never loaded cannot have set anything. `platforms/default-platform.ts` is the reader.
+ */
+export const BOOT_META = { name: "jx-boot", content: "launcher" } as const;
+
 export interface DocumentOptions {
   /** Where the asset tree is mounted. Defaults to {@link IN_PLACE}. */
   readonly base?: AssetBase | undefined;
@@ -39,6 +53,12 @@ export interface DocumentOptions {
    * or publishes the `__jxCloud` signal for the studio entry to build the adapter from. It must do
    * so SYNCHRONOUSLY — a module script with top-level await does not block a later script tag, and
    * the entry reads the global as it evaluates.
+   *
+   * **Declaring a boot module turns the dev-server fallback off.** A non-empty list stamps
+   * {@link BOOT_META} into the head, and a studio entry that then finds no adapter and no cloud
+   * signal draws a boot-failure screen instead of registering the dev-server adapter
+   * (`platforms/default-platform.ts`). A host that serves the HTTP protocol at its own origin and
+   * wants that fallback declares no boot module.
    */
   readonly boot?: readonly string[] | undefined;
   /** Document title. Defaults to "Jx Studio". */
@@ -66,12 +86,19 @@ export function studioShellHtml(options: DocumentOptions = {}): string {
     .map((path) => `    <link rel="stylesheet" href="${url(path)}" />`)
     .join("\n");
   const boot = (options.boot ?? []).map((mod) => `    ${scriptTag(mod)}`).join("\n");
+  /* Only when there IS a boot module: `packages/studio/index.html` is generated with none and CI
+     diffs it byte for byte, and the dev server it is served by is the one host that should fall
+     back. The `<head>` below stays a literal, attribute-free tag — Electrobun's macOS CEF path
+     injects its preload by splicing after that exact string. */
+  const bootMeta = boot
+    ? `    <meta name="${BOOT_META.name}" content="${BOOT_META.content}" />\n`
+    : "";
   return `<!doctype html>
 <html lang="en">
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>${options.title ?? "Jx Studio"}</title>
+${bootMeta}    <title>${options.title ?? "Jx Studio"}</title>
     <link rel="icon" href="${url(STUDIO_FAVICON)}" />
 ${links}
   </head>

package/src/hosting/stage.ts

@@ -23,6 +23,17 @@ import type { DocumentOptions } from "./document";
 /** The installed package root, resolved off this module rather than off a caller's cwd. */
 export const STUDIO_PACKAGE_DIR = resolve(import.meta.dir, "..", "..");
 
+/**
+ * Normalize a `Glob.scan` result to forward slashes. Private and un-exported, like
+ * `project-session.ts`'s own `toPosix()`: this is the one module under `src/` that touches
+ * filesystem paths at all, and its published `files` entry (`package.json`) covers `src/` but not
+ * the repo's dev-tooling `scripts/lib/posix-path.ts`, so a cross-boundary import here would 404 for
+ * anyone who installed this package rather than checked out the monorepo.
+ */
+function toPosix(p: string): string {
+  return p.replaceAll("\\", "/");
+}
+
 export interface StageOptions {
   /** Package root to read from — an installed copy, or a `--link` checkout. */
   readonly from?: string | undefined;
@@ -108,13 +119,13 @@ export async function stageStudioAssets(
     const dest = destOf(destDir, a.path, layout);
     if (a.dir) {
       await mkdir(dest, { recursive: true });
-      for (const rel of new Glob("**/*").scanSync(src)) {
-        const posix = rel.replaceAll("\\", "/");
+      for (const rawRel of new Glob("**/*").scanSync(src)) {
+        const posix = toPosix(rawRel);
         if (skipMap(posix)) {
           continue;
         }
-        const file = join(src, rel);
-        const to = join(dest, rel);
+        const file = join(src, posix);
+        const to = join(dest, posix);
         await mkdir(dirname(to), { recursive: true });
         await cp(file, to);
         written.push(`${a.path}/${posix}`);

package/src/i18n/i18n-commands.ts

@@ -204,8 +204,8 @@ export function i18nCommands(): AnyCommand[] {
          with its `requires` sentence. The palette's availability is the person's contract; an
          argument-only gate needs a shape the registry does not have. Same on `createTranslation`. */
       when: (ctx) => ctx.project.isMultilingual && ctx.document.open,
-      /* No `aiTool`, by §12.4's first deletion rule: this opens a surface for a person, and the
-         model has `open_document` for the file it names. */
+      /* No `aiTool`, by studio-ui-guidelines.md §12.4's first deletion rule: this opens a surface
+         for a person, and the model has `open_document` for the file it names. */
       run: async (_ctx, args) => {
         const source = addressedDocument("i18n.openTranslation", args);
         const locale = stringArg("i18n.openTranslation", args, "locale");
@@ -261,10 +261,11 @@ export function i18nCommands(): AnyCommand[] {
       /* The document history cannot hold this: the change is a file that did not exist, and
          `undo: "project"` would claim `project.json` moved, which it did not. */
       undo: "none",
-      /* No `aiTool`, by §12.4's second deletion rule: `createFileIn` awaits the New File prompt
-         for the name, which the loop does not count as interactive, and a cancel resolves `null`
-         with nothing thrown — a report would describe a file that was never made. An optional
-         `name` argument that skips the prompt is the way back in, and is a UX call (issue 273). */
+      /* No `aiTool`, by studio-ui-guidelines.md §12.4's second deletion rule: `createFileIn` awaits
+         the New File prompt for the name, which the loop does not count as interactive, and a
+         cancel resolves `null` with nothing thrown — a report would describe a file that was never
+         made. An optional `name` argument that skips the prompt is the way back in, and is a UX
+         call (issue 273). */
       run: async (_ctx, args) => {
         const source = addressedDocument("i18n.createTranslation", args);
         const locale = stringArg("i18n.createTranslation", args, "locale");
@@ -319,7 +320,8 @@ export function i18nCommands(): AnyCommand[] {
       group: "2_view",
       requires: "a project that declares more than one language",
       when: (ctx) => ctx.project.isMultilingual,
-      /* No `aiTool`, by §12.4's first deletion rule: the panel is a surface for a person. */
+      /* No `aiTool`, by studio-ui-guidelines.md §12.4's first deletion rule: the panel is a surface
+         for a person. */
       /* The panel is off the rail — it spends no rail slot and shifts no ⌘1-8 chord — so this
          command and the generated `panel.focus.i18n` are its only two doors, and both open the
          same one. The TITLES must differ even though the behaviour does not: the palette is a flat

package/src/new-project/location-fields.ts

@@ -4,9 +4,9 @@
  * Two shapes, chosen by the platform's `createDestination` (specs/desktop.md §4.5):
  *
  * - `"path"` (desktop, dev server): a required **Location** (absolute parent directory) plus the
- *   folder name. Desktop backs the Browse… button with the native dialog via `pickDirectory`; the
- *   dev server has no dialog, so the path is typed. Nothing is ever written to a directory the user
- *   did not name.
+ *   folder name. The Browse… button is backed by `pickDirectory` wherever the platform has one:
+ *   desktop's system dialog, and the dev server's `showDirectoryPicker` in a Chromium browser.
+ *   Elsewhere the path is typed. Nothing is ever written to a directory the user did not name.
  * - `"repo"` (cloud): the repository location — owner (personal account or organization), the
  *   repository name, and its visibility.
  *
@@ -21,6 +21,7 @@
  * @docs studio/projects/create
  */
 
+import { errorMessage } from "@jxsuite/schema/parse";
 import { getPlatform } from "../platform";
 import type { CreateProjectDestination, RepoInfo } from "../types";
 
@@ -253,6 +254,13 @@ export function setLocationVisibility(value: string): void {
  * Re-entrant by refusal rather than by disabling alone: the button is drawn disabled while the
  * native dialog is up, and a synthetic click does not consult that.
  *
+ * **Never a silent no-op, and never a rejection.** `null` from `pickDirectory` is the user
+ * cancelling, so nothing is said and the standing state is left alone. Anything else rejects with a
+ * displayable message (see `StudioPlatform.pickDirectory`), which lands in the destination error
+ * under the Location field, where typing a path clears it. The modal calls this as `void
+ * browseLocation(...)`, so a rejection escaping here would be an unhandled one: the exact "picked a
+ * folder and nothing happened" this contract exists to rule out.
+ *
  * @param rerender Repaint the wizard — once for the busy label, once for the answer.
  */
 export async function browseLocation(rerender: () => void): Promise<void> {
@@ -268,6 +276,11 @@ export async function browseLocation(rerender: () => void): Promise<void> {
       _parent = picked;
       _error = "";
     }
+  } catch (error) {
+    /* The dialog could not open, the folder could not be tagged, the backend was unreachable or
+       found no match, an RPC timed out. Whatever the platform, the sentence goes under Location. */
+    _error =
+      errorMessage(error) || "The folder could not be chosen. Type its path into Location instead.";
   } finally {
     _browsing = false;
     rerender();

package/src/new-project/new-project-modal.ts

@@ -46,7 +46,8 @@ import { getPlatform } from "../platform";
 import { installUrlOf } from "../platform-errors";
 import { hasAiCredentials } from "../services/ai-models";
 import { setPendingAgentPrompt } from "../services/agent-seed";
-import { initProjectRepo } from "../files/files";
+import { adoptCreatedProject } from "../services/project-adoption";
+import { notify } from "../services/notify";
 import { runImportHandoff } from "../services/import-seed";
 import { createAiCredentialsForm } from "../ui/ai-credentials-form";
 import { createManagedConnect } from "../ui/ai-managed-connect";
@@ -328,14 +329,29 @@ function finish(result: { root: string; config: ProjectConfig } | null) {
 
 /**
  * Every path out of the wizard that produced a project HERE: initialise version control for it,
- * then hand it to the caller. A scaffold is not a repository, and Delete and Rename are one click
- * away.
+ * open it, then hand it to the caller. A scaffold is not a repository and an unopened project is
+ * not a created one, and Delete and Rename are one click away.
  *
- * The Import path does not come through here any more — `import_site` creates the project, so the
- * obligation moved with it into `services/project-adoption.ts`, which both bootstrap tools share.
+ * `adoptCreatedProject` is the same sequence `create_project`/`import_site` run — this is the third
+ * caller `services/project-adoption.ts`'s own doc comment already names. It is what makes
+ * `project.new` from the command palette work at all while a project is open: that entry point
+ * never looks at what this promise resolves with (`newProjectCommands` below fires and forgets), so
+ * adopting has to happen HERE rather than being left to whichever caller opened the wizard.
+ *
+ * The Import path does not come through here — `import_site` creates the project, so it already
+ * runs this same sequence itself.
  */
 async function finishCreated(result: { root: string; config: ProjectConfig }) {
-  await initProjectRepo(result.root);
+  const { adopted, error, openedElsewhere } = await adoptCreatedProject(result.root, {
+    // The wizard runs outside the agent loop — there is never a batch to flush and re-anchor.
+    getTab: () => null,
+  });
+  if (!adopted && !openedElsewhere) {
+    notify.warn("Created the project, but could not open it here.", {
+      ...(error === null ? {} : { detail: error }),
+      source: "New Project",
+    });
+  }
   finish(result);
 }
 
@@ -680,7 +696,7 @@ export function newProjectCommands(): AnyCommand[] {
       menus: ["commandbar/overflow", "palette"],
       group: "1_file",
       /* No `aiTool`: application-level, refused at registration; it opens the wizard, and the
-         model's own door is `create_project` / `import_site` (§12.4). */
+         model's own door is `create_project` / `import_site` (studio-ui-guidelines.md §12.4). */
       run: (_commandCtx, args) => {
         const tab =
           (args as { tab?: unknown }).tab === undefined