@jxsuite/studio 5.2.0 → 5.4.0

package/src/panels/style-panel.ts

@@ -12,8 +12,8 @@
  * scheme layer, nested selector)`. It has always computed that tuple — it is the per-field key and
  * the five-branch if/else below — and it used to hide it behind three disconnected widgets on two
  * different bars. `target-line.ts` renders it as one sentence instead, and the three widgets are
- * gone: the breakpoint and scheme axes are selected on the pane context bar (region ⑦), and the
- * selector is the one axis this tab owns.
+ * gone: the breakpoint and scheme axes are selected on the pane context bar, and the selector is
+ * the one axis this tab owns.
  *
  * Every row then says where its value came from. `provenance.ts` supplies the vocabulary;
  * `computeInheritedSources()` supplies the donor breakpoint the cascade walk always knew and this
@@ -28,17 +28,18 @@
  * bound property, and an equal write is skipped. `renderOnly("rightPanel")` is gone from this file
  * with it.
  *
- * **Two controls are lists, and the list is the KIT MENU** (`surfaces/menu.ts`, §12.5). The unit
- * picker and the keyword suggestions were each an `sp-overlay` + `sp-menu` of their own; the Value
- * Source picker was a third. All three are `openMenu()` now, which is also how roving focus,
- * typeahead and Escape arrive here without a line of keyboard code.
+ * **Two controls are lists, and the list is the KIT MENU** (`surfaces/menu.ts`,
+ * `studio-ui-guidelines.md` §12.5). The unit picker and the keyword suggestions were each an
+ * `sp-overlay` + `sp-menu` of their own; the Value Source picker was a third. All three are
+ * `openMenu()` now, which is also how roving focus, typeahead and Escape arrive here without a line
+ * of keyboard code.
  *
  * **Nothing here is an island any more.** One control was: `specs/ui.md` §5.6 (Colour) was Pending,
  * so a colour row drew an announced `[part="control-host"]` and a lit `paintColorControl` filled
- * it, and that was the last Spectrum on this surface. §5.6 landed. The row is a `jx-color-field` in
- * the document beside every other control, its palette is a `jx-swatch-group` slotted into the
- * picker, and `ui/color-selector.ts` is what remains: which colours THIS PROJECT has named, which
- * is a question no kit element can answer.
+ * it, and that was the last Spectrum on this surface. `ui.md` §5.6 landed. The row is a
+ * `jx-color-field` in the document beside every other control, its palette is a `jx-swatch-group`
+ * slotted into the picker, and `ui/color-selector.ts` is what remains: which colours THIS PROJECT
+ * has named, which is a question no kit element can answer.
  *
  * @docs studio/design/style-inspector
  */
@@ -68,7 +69,6 @@ import {
   transactDoc,
 } from "../tabs/transact";
 import {
-  abbreviateValue,
   friendlyNameToVar,
   inferInputType,
   kebabToLabel,
@@ -337,7 +337,7 @@ export function resetAffectedDisclosure(): void {
  *
  * The breakpoint and the colour scheme are DEFINED in Project Settings › Contexts and SELECTED on
  * the pane context bar. A Target Line segment that opened its own list would be the third selector
- * §6.4 forbids, so it routes to the definition site through the same command the context bar's
+ * §6.2 forbids, so it routes to the definition site through the same command the context bar's
  * "Manage contexts…" footer runs.
  */
 function runCommand(id: string, args?: Record<string, unknown>): void {
@@ -543,7 +543,7 @@ interface ProvenanceCtx {
   signals: string[];
   clear: (prop: string) => void;
   /**
-   * Properties the selected elements DISAGREE about, and how many elements are selected (§6.5).
+   * Properties the selected elements DISAGREE about, and how many elements are selected (§6.7).
    *
    * Empty for a selection of one — which is what keeps every other branch of `provenanceOf`
    * reachable exactly as often as it was before the selection became a set.
@@ -727,7 +727,7 @@ interface RowActions {
   choices?: StyleChoice[];
   choicesLabel?: string;
   choose?: (value: string) => void;
-  /** The Value Source ladder for this position (§6.3). */
+  /** The Value Source ladder for this position (§6.6). */
   source?: {
     mode: SlotMode;
     caps: SlotMode[];
@@ -771,27 +771,30 @@ function isNumericValue(value: string): boolean {
 }
 
 /**
- * Kit glyph names for the values a button-group offers.
+ * The buttons a button-group row draws, and the overflow list it hands to the kit menu.
  *
- * Only names the kit ACTUALLY has (`@jxsuite/ui/icons`) are here, and every other value falls back
- * to `abbreviateValue`, which is the same fallback the group has always had for a value with no
- * icon. The alternative was to guess an approximation — `align-left` for `justify-content:
- * flex-start`, say, which is a text-alignment glyph — and a glyph that means something else is
- * worse than three letters that mean what they say. The seventeen names still missing are recorded
- * against the kit rather than approximated here.
+ * A value's glyph is its css-meta `$icons` entry VERBATIM: those values are kit manifest names
+ * (ui.md §8, one key space), so there is nothing to translate. A value with no entry — `nowrap`,
+ * `wrap-reverse`, `normal`, `auto` — draws its own CSS KEYWORD instead, in full and in lower case,
+ * and its button is the only kind that carries any text.
+ *
+ * The keyword is written out rather than abbreviated. It used to go through an `abbreviateValue`
+ * table in `utils/studio-utils.ts`, and four segments of a row that is otherwise pictures then read
+ * `no-wr`, `wr-rev`, `norm` and `auto` — a reader cannot decode three of them. `wr-rev` is as
+ * opaque as the glyph-less Display row this pass set out to fix, and it sat beside a wrap arrow
+ * that a reader COULD decode, so the row taught them the buttons were unreadable. A word takes
+ * about 30px more than a glyph; the group's text segments pay 6px of inline padding for it
+ * (`jx-action-group`), and no row draws more than two. That table had no other caller, so it went
+ * with the abbreviations rather than staying behind as a spelling nothing spells.
+ *
+ * There used to be a table here from css-meta's own semantic names (`display-flex`,
+ * `justify-start`) to the eight of them the kit happened to ship verbatim. It was a second spelling
+ * of glyph names beside the manifest, it had drifted from the translations the kit had already
+ * reasoned out, and every name it lacked resolved to `""` in silence, which is how the whole
+ * Display row shipped as abbreviations. So there is no runtime `hasIcon` guard either: a name the
+ * manifest lacks is a red `tests/metadata.test.ts`, which is where a miss is caught before it ships
+ * rather than degraded after.
  */
-const BUTTON_GLYPHS: Readonly<Record<string, string>> = {
-  "arrow-down": "arrow-down",
-  "arrow-left": "arrow-left",
-  "arrow-right": "arrow-right",
-  "arrow-up": "arrow-up",
-  "text-align-center": "text-align-center",
-  "text-align-justify": "text-align-justify",
-  "text-align-left": "text-align-left",
-  "text-align-right": "text-align-right",
-};
-
-/** The buttons a button-group row draws, and the overflow list it hands to the kit menu. */
 function buttonGroup(
   entry: CssPropertyEntry,
   rowKey: string,
@@ -806,12 +809,12 @@ function buttonGroup(
       ? enumValues.filter((v) => !buttonValues.includes(v))
       : [];
   const buttons = values.map((v) => {
-    const icon = BUTTON_GLYPHS[iconMap[v] ?? ""] ?? "";
+    const icon = iconMap[v] ?? "";
     return {
       icon,
       row: rowKey,
       selected: v === value,
-      text: icon === "" ? abbreviateValue(v) : "",
+      text: icon === "" ? v : "",
       title: v,
       value: v,
     };
@@ -1060,7 +1063,7 @@ function fieldRow(
   row.placeholder = placeholder;
   applyChip(row, actions, opts.provenance);
 
-  // The Value Source ladder (§6.3), and only where the position has one to offer. A longhand child
+  // The Value Source ladder (§6.6), and only where the position has one to offer. A longhand child
   // Is not a document position of its own — its value is a slice of the shorthand above it — so it
   // Carries no chip, which is what it has always done.
   if (!opts.child) {
@@ -1395,7 +1398,7 @@ function buildView(canvasMode: () => string): StylePanelView {
       return emptyView("Open a page to style what you click.", true);
     }
     // No separate `Styling: <h1>` header. It said the same thing the Target Line's scope chip says,
-    // Except that it said it as a caption, after the fact, and without the blast radius (§6.1).
+    // Except that it said it as a caption, after the fact, and without the blast radius (§6.2).
     return buildEditor(tab, node, {
       effectiveStyle: getEffectiveStyle(node.style),
       stylebookSelector: shell.stylebook.selection,
@@ -1445,7 +1448,7 @@ function buildEditor(
   const mediaTab = tab.session.ui.activeMedia || null;
   const { activeSelector } = tab.session.ui;
 
-  // ── Scheme-layer routing (spec §9.5) ────────────────────────────────────────
+  // ── Scheme-layer routing (spec.md §9.5) ─────────────────────────────────────
   // With the tab-bar scheme control forcing a scheme that has a matching declared scheme query,
   // Base-context edits target that scheme's `@--name` block — no extra sidebar tabs. Breakpoint
   // Tabs stay breakpoint-scoped (scheme × breakpoint compound blocks are unsupported).
@@ -1476,7 +1479,7 @@ function buildEditor(
     ]),
   ];
 
-  // ── The Target Line (§6.1) ─────────────────────────────────────────────────
+  // ── The Target Line (§6.2) ─────────────────────────────────────────────────
   const stylebookTag = stylebookTagOf(stylebookSelector);
   const elementLabel =
     stylebookTag ?? (typeof node.tagName === "string" ? node.tagName : "element");
@@ -1510,7 +1513,8 @@ function buildEditor(
       },
       onAddCustom: () => {
         // One flow, through `ui/layers.ts` — the imperative `<input>` this replaces was appended to
-        // A bar lit-html owns, bypassing both the renderer and the overlay stack (§11.4).
+        // A bar lit-html owns, bypassing both the renderer and the overlay stack (§6.2, "Nested
+        // Selector Context").
         void showPromptDialog("Add Selector", {
           confirmLabel: "Use",
           message: "A state or nested rule to edit under this element.",
@@ -1537,7 +1541,7 @@ function buildEditor(
     style === ownRootStyle
       ? activeStyle
       : resolveContextStyle(ownRootStyle, activeSelector, editMedia);
-  // ── The selection, and what it means to commit to it (§6.5) ────────────────
+  // ── The selection, and what it means to commit to it (§6.7) ────────────────
   // Every selected element gets the same write, inside ONE `transactDoc` — so setting padding on
   // Six cards is one decision and one undo step. With one element selected this loop runs once
   // Against `sel` and is indistinguishable from the single-target commit it replaces.

package/src/panels/stylebook-panel.ts

@@ -196,7 +196,6 @@ export async function renderStylebookMode(
   const stage = await ctx.drawStage(
     surface,
     {
-      columnHeader: "hidden",
       frame: "boards",
       framePart: "panzoom",
       // The bar floats over the stage, so the catalogue starts below it.

package/src/panels/tab-strip.ts

@@ -2,7 +2,7 @@
 /**
  * Tab strip — one strip PER PANE, above each pane's editor.
  *
- * A tab belongs to a pane and the pane is what splits (§4.3), so the strip is a rendering of
+ * A tab belongs to a pane and the pane is what splits (§14.4), so the strip is a rendering of
  * `Pane.tabOrder` / `Pane.activeTabId`, not of a workspace-wide list. The host for each pane is
  * addressed by REGION id — `pane.primary/tabs`, `pane.secondary/tabs` — rather than by element id,
  * so the shell can move or rename the divs without touching this file.
@@ -185,7 +185,8 @@ export function mount(host: HTMLElement) {
         source.data.type === "tab"
           ? { kind: "tab", tabId: source.data.tabId as string }
           : { kind: "file", path: source.data.path as string };
-      // The tail target does not exist until a pane with no tabs is asked to grow one (§7).
+      // The tail target does not exist until a pane with no tabs is asked to grow one (§14.4's
+      // "Between panes" row; `project` draws it).
       render();
       // `render()` alone does not write `dragKey` — only `syncDrag()` does — so without this the
       // Source chip's `data-dragging` mark would not appear until the pointer's first move.
@@ -566,8 +567,8 @@ function project(pane: Pane): TabStripValues {
     tabs: pane.tabOrder.flatMap((id, index) => chipView(pane, id, index, labels)),
     trailing: _overflowing.get(pane.id) === true,
     trailingGlyph: "⌄",
-    // ONE accessible name (§10): the glyph is hidden, so `title` is both the tooltip and the name
-    // — `title` + a matching `aria-label` would announce it twice.
+    // ONE accessible name (`studio-ui-guidelines.md` §10): the glyph is hidden, so `title` is both
+    // The tooltip and the name — `title` + a matching `aria-label` would announce it twice.
     trailingTitle: "Show hidden tabs",
   };
 }
@@ -594,9 +595,10 @@ function chipView(
   if (!tab) {
     return [];
   }
-  /* The draft pill (§7.6). On the CHIP, not only inside the entry editor: the mistake this
-     prevents — publishing something you believed was private — is made while glancing at a row of
-     tabs, and it is made about a document that may not even be the active one. */
+  /* The draft pill (`site-architecture.md` §7.6). On the CHIP, not only inside the entry editor:
+     the mistake this prevents — publishing something you believed was private — is made while
+     glancing at a row of tabs, and it is made about a document that may not even be the active
+     one. */
   const pill = entryDraftPill(tab);
   return [
     {
@@ -678,8 +680,9 @@ function adoptChip(host: HTMLElement, element: HTMLElement, id: string): void {
 
 /**
  * Make a strip's OWN element a drop target — the empty tail after the last chip, and, for an empty
- * pane growing one during a drag (§7), the whole of it. Innermost wins, so a chip under the pointer
- * answers first; this only ever resolves a drop that landed on the strip itself.
+ * pane growing one during a drag (§14.4, "Between panes"), the whole of it. Innermost wins, so a
+ * chip under the pointer answers first; this only ever resolves a drop that landed on the strip
+ * itself.
  */
 function adoptStrip(host: HTMLElement, element: HTMLElement): void {
   _stripDnd.get(host)?.();
@@ -848,11 +851,11 @@ export function dismissOverflowMenu() {
  * List the off-screen tabs. Falls back to every tab when nothing measures as hidden, because an
  * empty menu is a dead control and happy-dom (plus any zero-height layout) measures everything at 0.
  *
- * **The kit menu, not a popover of this strip's own** (guidelines §8.4). `surfaces/menu.ts` owns
- * the panel, the roving caret, the typeahead, Escape and the light dismissal, and it clamps the
- * panel into the viewport once it has been laid out — so the `right:`/`top:` arithmetic that used
- * to sit in a style attribute here is one `place` callback, measured against the panel's real box
- * instead of guessed from the chevron's.
+ * **The kit menu, not a popover of this strip's own** (`studio-ui-guidelines.md` §8.4).
+ * `surfaces/menu.ts` owns the panel, the roving caret, the typeahead, Escape and the light
+ * dismissal, and it clamps the panel into the viewport once it has been laid out — so the
+ * `right:`/`top:` arithmetic that used to sit in a style attribute here is one `place` callback,
+ * measured against the panel's real box instead of guessed from the chevron's.
  *
  * A row states whether it is the tab the pane is already showing. The strip's own chips carry that
  * as `aria-selected`, and a menu row cannot: `checked` on every row is the shape this shell already
@@ -1038,12 +1041,12 @@ function placedTabItems(tab: Tab): MenuRowProjection[] {
  * beside the gesture that needs them (`surfaces/tab-strip.json`), so what arrives here is the tab
  * and the point — which is everything a menu is a function of.
  *
- * **The rows go to the kit menu** (`surfaces/menu.ts`, guidelines §12.5), which is why there is no
- * row template in this file any more. Three things that were written here went with it: the clamp
- * that kept a right-click near the screen edge readable — `onMenuToggle` clamps every panel once it
- * has been laid out, against the panel's real box rather than a guessed one — the `Needs …` line a
- * disabled row prints, and the refusal to dismiss when a disabled row is clicked, which is
- * `jx-menu-item`'s own `onClick` guard.
+ * **The rows go to the kit menu** (`surfaces/menu.ts`, `studio-ui-guidelines.md` §12.5), which is
+ * why there is no row template in this file any more. Three things that were written here went with
+ * it: the clamp that kept a right-click near the screen edge readable — `onMenuToggle` clamps every
+ * panel once it has been laid out, against the panel's real box rather than a guessed one — the
+ * `Needs …` line a disabled row prints, and the refusal to dismiss when a disabled row is clicked,
+ * which is `jx-menu-item`'s own `onClick` guard.
  */
 function openTabContextMenu(tab: Tab, clientX: number, clientY: number) {
   dismissTabContextMenu();
@@ -1340,9 +1343,9 @@ async function confirmClose(tab: Tab): Promise<boolean> {
  *
  * **Three ways out, not two.** This asked "Close without saving?" over a two-way confirm, so the
  * only buttons were the one that threw the work away and the one that did nothing — a dialog that
- * cannot do the thing the user most likely wants. §8.7's table assigns "Unsaved-work decisions" to
- * `showSaveDiscardDialog`, and this is that decision — except when a save is not one of the ways
- * out at all, which is {@link confirmClose}'s job to tell apart.
+ * cannot do the thing the user most likely wants. `studio-ui-guidelines.md` §8.7's table assigns
+ * "Unsaved-work decisions" to `showSaveDiscardDialog`, and this is that decision — except when a
+ * save is not one of the ways out at all, which is {@link confirmClose}'s job to tell apart.
  *
  * **A failed save must not close the tab.** `saveFile` reports its own failures and returns whether
  * the bytes landed; treating "Save" as "save and then close regardless" would turn a write error

package/src/platform-errors.ts

@@ -8,8 +8,8 @@
  * **RFC 9457 reconciles cleanly with this, because a problem's `type` IS the code.** A backend
  * answering `type: "https://jxsuite.com/problems/needs-installation-access"` is saying exactly what
  * `code: "needs_installation_access"` said; `problemSlug` derives the one from the other, and
- * `installUrl` is the extension member (§3.2) that type documents. So this module reads both, and
- * every surface above it keeps branching on `code` without knowing which shape arrived.
+ * `installUrl` is the extension member (RFC 9457 §3.2) that type documents. So this module reads
+ * both, and every surface above it keeps branching on `code` without knowing which shape arrived.
  */
 
 import { problemSlug } from "@jxsuite/protocol";

package/src/platform.ts

@@ -13,20 +13,60 @@
  *
  * **Every call is counted.** `getPlatform()` hands out a counting proxy, not the raw adapter, so
  * "is Studio waiting on I/O?" is one number rather than thirty hand-instrumented methods
- * (`probe.idle()` condition 4, spec §13.5). Wrapping at the READ point rather than at
+ * (`probe.idle()`'s in-flight I/O condition, §13.5). Wrapping at the READ point rather than at
  * `registerPlatform` is deliberate: desktop pre-registers its adapter on `window.__jxPlatform`
  * without ever calling the registrar, and this is the seam both paths share.
  */
 
 import type { StudioPlatform } from "./types";
 
-const g = globalThis as unknown as { __jxPlatform?: StudioPlatform };
+/** What a launcher's boot module recorded when its adapter could not be constructed. */
+export interface LauncherBootError {
+  message: string;
+  stack?: string | undefined;
+}
+
+/**
+ * A launcher's announcement that it owns this window's adapter (spec/desktop.md §3.3).
+ *
+ * Published by the launcher boot module's FIRST import, before any other module in its bundle
+ * evaluates, so it exists even when a later import throws. Present with no adapter registered, it
+ * means the launcher failed, and Studio must say so rather than fall back to the dev server. That
+ * fallback is what desktop 5.0.0-5.1.3 did for months: its init bundle threw on import, and every
+ * window ran the dev-server adapter against a `views://` origin with nothing behind it.
+ */
+export interface LauncherSignal {
+  /** Which launcher announced (`"electrobun"`, `"chromium"`), once its boot module's body ran. */
+  launcher?: string | undefined;
+  /** The first error the page raised during boot, or the adapter factory's own throw. */
+  error?: LauncherBootError | undefined;
+}
+
+const g = globalThis as unknown as {
+  __jxPlatform?: StudioPlatform;
+  __jxLauncher?: LauncherSignal;
+};
 
 /** @param {StudioPlatform} platform */
 export function registerPlatform(platform: StudioPlatform) {
   g.__jxPlatform = platform;
 }
 
+/**
+ * Publish the launcher signal on `globalThis.__jxLauncher`, or return the one already published.
+ *
+ * Idempotent, so an error recorded by the first announcer survives a second call.
+ */
+export function announceLauncher(): LauncherSignal {
+  g.__jxLauncher ??= {};
+  return g.__jxLauncher;
+}
+
+/** The launcher signal, when a launcher's boot module announced itself in this window. */
+export function launcherSignal(): LauncherSignal | undefined {
+  return g.__jxLauncher;
+}
+
 // ─── In-flight accounting ─────────────────────────────────────────────────────
 
 /** Method name → how many of its calls have not settled. Entries are deleted at zero. */
@@ -36,8 +76,8 @@ const inFlight = new Map<string, number>();
  * One entry per platform call whose promise has not settled, named by its method.
  *
  * Repeats are meaningful: two concurrent `gitStatus` reads are two reasons the shell is not
- * settled, and the rejection message that names them is the whole point of §13.4 — 115 sleeps were
- * 115 places that could not fail.
+ * settled, and the rejection message that names them is the whole point of "Determinism" in
+ * `scripts/screenshots/README.md` — 115 sleeps were 115 places that could not fail.
  */
 export function platformInFlight(): string[] {
   const names: string[] = [];

package/src/platforms/cloud.ts

@@ -496,6 +496,16 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
       return data.content;
     },
 
+    /* Raw bytes. The session origin serves this route, so no CORS question arises — the shell and
+       the API are the same origin on cloud, which is exactly what `assetSpace: "repo"` is about. */
+    async readFileBytes(path: string) {
+      const res = await api(`/file/bytes?path=${encodeURIComponent(path)}`);
+      if (!res.ok) {
+        throw new Error(await errorMessage(res, `Failed to read file bytes: ${path}`));
+      }
+      return res.arrayBuffer();
+    },
+
     async writeFile(path: string, content: string) {
       const res = await api("/file", {
         method: "PUT",
@@ -724,7 +734,7 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
      *
      * Degrades to `{}` rather than throwing: a backend too old to serve the route, or a project
      * whose extensions the session cannot compose, keeps the bundled core schemas. That fallback
-     * under-suggests extension extras but never reports false errors (§5.3).
+     * under-suggests extension extras but never reports false errors (extensions.md §5.3).
      */
     async fetchProjectSchemas(): Promise<ProjectSchemasResponse> {
       try {

package/src/platforms/default-platform.ts

@@ -1,15 +1,33 @@
 /// <reference lib="dom" />
 /**
- * Chooses the default PAL adapter when no platform was pre-registered on `window.__jxPlatform`.
+ * Chooses the default PAL adapter when no platform was pre-registered on `window.__jxPlatform` — or
+ * refuses to, when a launcher was supposed to have registered one.
  *
  * The cloud shell (the platform repo's `web/edit-init.ts`) publishes a `window.__jxCloud` signal
  * _instead of_ constructing the adapter itself, so the cloud adapter — and its collab WebSocket
  * client, which owns the shared `Y.Doc` — is created HERE, inside the studio bundle, sharing
  * studio's single `yjs` instance. Creating it in the shell bundle loads a SECOND `yjs`, which
  * breaks collab's cross-module `instanceof` checks (the Y↔JxDocOp conversion silently stops
- * reconciling). The dev server sends no signal and falls back to the dev-server adapter; desktop
- * pre-registers its own adapter on `__jxPlatform`, so this resolver never runs there.
+ * reconciling). The dev server sends no signal and gets the dev-server adapter.
+ *
+ * **This resolver DOES run on desktop — whenever desktop failed.** A launcher registers its own
+ * adapter on `__jxPlatform` from a boot module that evaluates before this bundle, and this header
+ * used to conclude that the resolver never ran there. That held only while the boot module worked.
+ * Desktop 5.0.0 to 5.1.3 shipped an init bundle that threw on import, nothing registered, and this
+ * resolver answered with the dev-server adapter inside a `views://` window: every panel drew,
+ * "Create Project" said "Failed to fetch", and Browse did nothing at all. A half-working app is the
+ * worst failure a launcher can have, because it reads as a bug in whatever the user clicked last.
+ *
+ * So the fallback is now conditional on there being nobody it could be standing in for.
+ * {@link bootRefusal} is that decision, and {@link resolveDefaultPlatform} throws
+ * {@link PlatformUnavailableError} rather than guess; `studio.ts` catches it and draws the
+ * boot-failure screen (`surfaces/boot-failure.ts`) in place of the frame.
+ *
+ * @docs extending/embedding/platform-adapter
  */
+import { BOOT_META } from "../hosting/document";
+import { launcherSignal } from "../platform";
+import type { LauncherSignal } from "../platform";
 import type { StudioPlatform } from "../types";
 import type { CloudProject } from "./cloud";
 import { createCloudPlatform } from "./cloud";
@@ -20,8 +38,127 @@ export interface CloudSignal {
   project: CloudProject | null;
 }
 
-/** Returns the cloud adapter when the shell signalled cloud, else the dev-server adapter. */
+/**
+ * Why Studio will not fall back to the dev-server adapter, most specific evidence first.
+ *
+ * - `launcher` — a launcher's boot module announced itself (`globalThis.__jxLauncher`) and still no
+ *   adapter was registered. The strongest evidence there is: the launcher ran, failed, and may have
+ *   recorded why. The error is deliberately NOT copied here — the failure view reads
+ *   `launcherSignal()?.error` when it renders, so an error recorded after this was decided still
+ *   reaches the screen.
+ * - `declared` — the document carries {@link BOOT_META}, so its host declared a boot module, and
+ *   nothing announced. The boot script never ran: a 404, a syntax error, a blocked load.
+ * - `scheme` — neither, but the page was opened from `views:` or `file:`. The dev-server adapter is
+ *   relative `fetch`, `EventSource` and a WebSocket against the page's own origin, and those two
+ *   schemes have no HTTP server behind them by construction. This covers a staged `index.html` old
+ *   enough to predate the meta.
+ */
+export type BootRefusal =
+  | { kind: "launcher"; launcher: string | undefined }
+  | { kind: "declared" }
+  | { kind: "scheme"; protocol: string };
+
+/** The four facts {@link bootRefusal} decides from, read once so the rule itself stays pure. */
+export interface BootEnvironment {
+  /** The launcher signal, when a launcher's boot module announced itself. */
+  launcher: LauncherSignal | undefined;
+  /** Whether the cloud shell published its `__jxCloud` signal. */
+  cloud: boolean;
+  /** Whether the document carries the {@link BOOT_META} marker. */
+  declared: boolean;
+  /** `location.protocol`, colon included. */
+  protocol: string;
+}
+
+/**
+ * Schemes the dev-server adapter can never work from.
+ *
+ * ONLY these two, and the list is short on purpose. The embedding docs promise that a host serving
+ * the HTTP protocol reuses the stock dev-server adapter unchanged, and a third-party shell may well
+ * serve it through a custom scheme — `tauri://localhost` proxies to a real server. Refusing every
+ * scheme that is not `http:` would break that host to cover a case the meta and the launcher signal
+ * already cover for every host this repository ships. `views:` is Electrobun's own bundle scheme
+ * and `file:` is a document opened from disk; neither can be proxying anything. happy-dom's
+ * `about:` is absent for the same reason, which is also what lets a test import the entry without
+ * inventing a URL.
+ */
+const BACKENDLESS_SCHEMES: ReadonlySet<string> = new Set(["views:", "file:"]);
+
+/** Read the boot environment from the live globals and document. */
+export function bootEnvironment(): BootEnvironment {
+  const doc = (globalThis as { document?: Document }).document;
+  const meta = `meta[name="${BOOT_META.name}"][content="${BOOT_META.content}"]`;
+  return {
+    cloud: (globalThis as unknown as { __jxCloud?: CloudSignal }).__jxCloud != null,
+    declared: doc?.querySelector(meta) != null,
+    launcher: launcherSignal(),
+    protocol: (globalThis as { location?: Location }).location?.protocol ?? "",
+  };
+}
+
+/**
+ * Whether the dev-server fallback must be refused, and why — `null` when it may run.
+ *
+ * The order is the argument. A launcher signal beats the cloud signal because it is direct evidence
+ * of a launcher that failed, and a window is not both. The cloud signal beats the meta because the
+ * cloud shell declares a boot module too — `edit-init.js` IS its boot module — and publishing the
+ * signal is that module succeeding.
+ *
+ * @param env The environment to judge; the live one by default.
+ */
+export function bootRefusal(env: BootEnvironment = bootEnvironment()): BootRefusal | null {
+  if (env.launcher) {
+    return { kind: "launcher", launcher: env.launcher.launcher };
+  }
+  if (env.cloud) {
+    return null;
+  }
+  if (env.declared) {
+    return { kind: "declared" };
+  }
+  if (BACKENDLESS_SCHEMES.has(env.protocol)) {
+    return { kind: "scheme", protocol: env.protocol };
+  }
+  return null;
+}
+
+/** The console's one-line account of a refusal; the screen says it at more length. */
+function refusalMessage(refusal: BootRefusal): string {
+  switch (refusal.kind) {
+    case "launcher": {
+      return `Jx Studio's launcher (${refusal.launcher ?? "unnamed"}) announced itself but registered no platform adapter.`;
+    }
+    case "declared": {
+      return "Jx Studio's page declares a boot module, but nothing registered a platform adapter.";
+    }
+    default: {
+      return `Jx Studio was opened from a ${refusal.protocol} URL, which has no backend for the dev-server adapter.`;
+    }
+  }
+}
+
+/** Thrown by {@link resolveDefaultPlatform} when {@link bootRefusal} refuses the fallback. */
+export class PlatformUnavailableError extends Error {
+  readonly refusal: BootRefusal;
+
+  constructor(refusal: BootRefusal) {
+    super(refusalMessage(refusal));
+    this.name = "PlatformUnavailableError";
+    this.refusal = refusal;
+  }
+}
+
+/**
+ * The cloud adapter when the shell signalled cloud, else the dev-server adapter.
+ *
+ * @throws {PlatformUnavailableError} When a launcher was declared or announced and registered
+ *   nothing, or the page's scheme has no server behind it — see {@link bootRefusal}.
+ */
 export function resolveDefaultPlatform(): StudioPlatform {
+  const refusal = bootRefusal();
+  if (refusal) {
+    throw new PlatformUnavailableError(refusal);
+  }
   const cloud = (globalThis as unknown as { __jxCloud?: CloudSignal }).__jxCloud;
   return cloud ? createCloudPlatform(cloud.project) : createDevServerPlatform();
 }

package/src/platforms/devserver.ts

@@ -320,7 +320,12 @@ export function createDevServerPlatform() {
      * undefined and the modal falls back to a typed Location field.
      *
      * The picked handle carries no filesystem path, so it is resolved by the id the picker tags the
-     * folder with (see `@jxsuite/studio/directory-picker`).
+     * folder with (see `@jxsuite/studio/directory-picker`). Resolves `null` only when the user
+     * dismisses the chooser; every other failure rejects with a sentence the modal shows under
+     * Location. So `locate` keeps the helper's contract: `null` is "no folder holds this id" (the
+     * route's 200 `{ path: null }`), and a non-ok answer throws the problem the server sent rather
+     * than posing as a miss. A network failure (`TypeError: Failed to fetch`, e.g. a page that is
+     * not being served by the dev server at all) propagates as is, and the picker names it.
      */
     ...(canPickDirectory()
       ? {
@@ -330,9 +335,11 @@ export function createDevServerPlatform() {
                 `/__studio/locate-directory?name=${encodeURIComponent(name)}&id=${encodeURIComponent(id)}`,
               );
               if (!res.ok) {
-                return null;
+                // A proxy, or a `views://` host with no dev server behind it, may answer in HTML.
+                const body: unknown = await res.json().catch(() => null);
+                throw new Error(problemMessage(body, res.status));
               }
-              const found = await readJson<{ path?: string }>(res);
+              const found = await readJson<{ path?: string | null }>(res);
               return found.path ?? null;
             });
           },
@@ -383,6 +390,19 @@ export function createDevServerPlatform() {
       return data.content;
     },
 
+    /**
+     * Raw bytes, undecoded. Same-origin here, so the response body is simply the file.
+     *
+     * @param {string} path
+     */
+    async readFileBytes(path: string) {
+      const res = await fetch(`/__studio/file/bytes?path=${encodeURIComponent(serverPath(path))}`);
+      if (!res.ok) {
+        throw new Error(`Failed to read file bytes: ${path}`);
+      }
+      return res.arrayBuffer();
+    },
+
     /**
      * @param {string} path
      * @param {string} content