@jxsuite/studio 6.1.0 → 6.1.2

package/src/panels/tab-drop.ts

@@ -18,7 +18,10 @@
 
 import { extractClosestEdge } from "@atlaskit/pragmatic-drag-and-drop-hitbox/closest-edge";
 import { getReorderDestinationIndex } from "@atlaskit/pragmatic-drag-and-drop-hitbox/util/get-reorder-destination-index";
-import type { Edge } from "@atlaskit/pragmatic-drag-and-drop-hitbox/closest-edge";
+import type { Edge } from "@atlaskit/pragmatic-drag-and-drop-hitbox/types";
+import type { ElementDragPayload } from "@atlaskit/pragmatic-drag-and-drop/adapter/element-adapter";
+import type { DropTargetRecord } from "@atlaskit/pragmatic-drag-and-drop/types";
+import { isJsonObject } from "@jxsuite/schema/guards";
 import {
   activateTab,
   closePane,
@@ -54,8 +57,13 @@ export interface FileDragData extends Record<string, unknown> {
 
 export type TabDropSourceData = TabDragData | FileDragData;
 
-/** A slot in a strip — a chip's edge, or the strip's own empty tail when `tabId` is absent. */
-export interface TabSlotTarget extends Record<string, unknown> {
+/**
+ * A slot in a strip — a chip's edge, or the strip's own empty tail when `tabId` is absent.
+ *
+ * Target records are keyed by symbols as well as strings (pragmatic-dnd's `DropTargetRecord`), and
+ * a chip's carries one: `attachClosestEdge` stores the edge under a symbol key.
+ */
+export interface TabSlotTarget extends Record<string | symbol, unknown> {
   type: "tab-slot";
   paneId: string;
   tabId?: string;
@@ -63,17 +71,17 @@ export interface TabSlotTarget extends Record<string, unknown> {
   index: number;
 }
 
-export interface TabSlotRefusedTarget extends Record<string, unknown> {
+export interface TabSlotRefusedTarget extends Record<string | symbol, unknown> {
   type: "tab-slot-refused";
 }
 
 /** The right band of the last pane's stage, armed only while the grid is under {@link MAX_PANES}. */
-export interface PaneEdgeTarget extends Record<string, unknown> {
+export interface PaneEdgeTarget extends Record<string | symbol, unknown> {
   type: "pane-edge";
   paneId: string;
 }
 
-export interface PaneEdgeRefusedTarget extends Record<string, unknown> {
+export interface PaneEdgeRefusedTarget extends Record<string | symbol, unknown> {
   type: "pane-edge-refused";
 }
 
@@ -93,8 +101,11 @@ export type TabDropTarget =
  * anything else this module has no branch for) is refused at the SOURCE and never reaches a target
  * closure at all.
  */
-export function isTabDropSource(data: Record<string, unknown>): data is TabDropSourceData {
-  return data.type === "tab" || (data.type === "file-tree" && data.entryType === "file");
+export function isTabDropSource(data: unknown): data is TabDropSourceData {
+  return (
+    isJsonObject(data) &&
+    (data.type === "tab" || (data.type === "file-tree" && data.entryType === "file"))
+  );
 }
 
 /**
@@ -142,7 +153,7 @@ function edgeIndex(target: TabSlotTarget, edge: Edge | null): number {
 }
 
 async function resolveTabSlotDrop(source: TabDropSourceData, target: TabSlotTarget): Promise<void> {
-  const edge = extractClosestEdge(target as unknown as Record<string | symbol, unknown>);
+  const edge = extractClosestEdge(target);
   if (source.type === "tab") {
     if (source.paneId === target.paneId) {
       const pane = paneById(target.paneId);
@@ -202,18 +213,23 @@ async function resolvePaneEdgeDrop(
  * `undefined` for a drag cancelled off every target — both are legal and both mean nothing landed.
  */
 export async function resolveTabDrop(
-  source: { data: Record<string, unknown> },
-  target: { data: Record<string, unknown> } | undefined,
+  source: Pick<ElementDragPayload, "data">,
+  target: Pick<DropTargetRecord, "data"> | undefined,
 ): Promise<void> {
   if (!target || !isTabDropSource(source.data)) {
     return;
   }
   const sourceData = source.data;
   if (target.data.type === "tab-slot") {
+    /* SAFETY: a `tab-slot` record is only ever produced by `tab-strip.ts`'s two `getData`
+       closures (a chip's and a strip tail's), and both write a string `paneId` and a numeric
+       `index` beside the type, with `tabId` only on a chip's. */
     await resolveTabSlotDrop(sourceData, target.data as TabSlotTarget);
     return;
   }
   if (target.data.type === "pane-edge") {
+    /* SAFETY: a `pane-edge` record is only ever produced by `pane-grid.ts`'s edge-zone `getData`,
+       whose `PaneEdgeData` pairs that type with a string `paneId`. */
     await resolvePaneEdgeDrop(sourceData, target.data as PaneEdgeTarget);
   }
   // `tab-slot-refused` / `pane-edge-refused` / anything else: nothing.

package/src/panels/tab-strip.ts

@@ -62,6 +62,8 @@ import { activeRegistry } from "../commands/active-registry";
 import { runActiveReported, runReported } from "../commands/run-reported";
 import { PRESET_LABELS } from "../workspace/pane-derive";
 import { localeLabel } from "@jxsuite/schema/locale";
+import { isBoolean } from "@jxsuite/schema/guards";
+import type { CommandArgValues } from "../commands/command-args";
 import { tabOfPane } from "../canvas/canvas-surface";
 import { mediaDisplayName } from "./shared";
 import { mountTabStripSurface } from "../surfaces/tab-strip";
@@ -183,8 +185,8 @@ export function mount(host: HTMLElement) {
       }
       _drag =
         source.data.type === "tab"
-          ? { kind: "tab", tabId: source.data.tabId as string }
-          : { kind: "file", path: source.data.path as string };
+          ? { kind: "tab", tabId: source.data.tabId }
+          : { kind: "file", path: source.data.path };
       // 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();
@@ -198,6 +200,9 @@ export function mount(host: HTMLElement) {
       }
       const [target] = location.current.dropTargets;
       const data = target?.data;
+      /* SAFETY: a `tab-slot` record comes only from this module's own two `getData` closures (a
+         chip's in `adoptChip`, the tail's in `adoptStrip`), and both write a numeric `index` and a
+         string `paneId` beside that type. */
       _over =
         data?.type === "tab-slot"
           ? {
@@ -249,7 +254,7 @@ export function mount(host: HTMLElement) {
         void tab.session.openedFrom;
         // The draft pill is on the chip, so the chip has to repaint when the flag changes — reading
         // The absent key tracks its ADDITION too, which is the transition that matters most.
-        void tab.doc.content?.frontmatter?.[DRAFT_FIELD];
+        void tab.doc.content.frontmatter[DRAFT_FIELD];
       }
       // An edit is a commitment: a preview tab with unsaved changes is no longer disposable, and
       // The dirty flags this effect already tracks are exactly the signal.
@@ -370,8 +375,8 @@ function paint(pane: Pane, host: HTMLElement): void {
        microtask later — so a strip whose one tab has just come back has no tab marked current at
        the instant this runs. The flow already knows which chip it wants; asking the tree instead
        is asking a question we have the answer to, and getting it one tick early. */
-    ([...strip.children] as HTMLElement[])
-      .find((chip) => chip.dataset.tab === pane.activeTabId)
+    [...strip.children]
+      .find((chip) => chip instanceof HTMLElement && chip.dataset.tab === pane.activeTabId)
       ?.scrollIntoView({ block: "nearest", inline: "nearest" });
   }
 
@@ -801,8 +806,8 @@ function onWheel(e: WheelEvent) {
   if (e.ctrlKey) {
     return;
   }
-  const el = e.currentTarget as HTMLElement;
-  if (el.scrollWidth <= el.clientWidth) {
+  const el = e.currentTarget;
+  if (!(el instanceof HTMLElement) || el.scrollWidth <= el.clientWidth) {
     return;
   }
   const delta = Math.abs(e.deltaX) > Math.abs(e.deltaY) ? e.deltaX : e.deltaY;
@@ -832,7 +837,9 @@ export function hiddenTabIds(paneId: string = workspace.activePaneId): string[]
   const left = strip.scrollLeft;
   const right = left + strip.clientWidth;
   const hidden: string[] = [];
-  const chips = [...strip.querySelectorAll('[part="tab"]')] as HTMLElement[];
+  /* Typed, not filtered: a chip's position is what pairs it with `pane.tabOrder[index]`, so dropping
+     a node here would shift every later chip onto the wrong tab id. */
+  const chips = [...strip.querySelectorAll<HTMLElement>('[part="tab"]')];
   for (const [index, chip] of chips.entries()) {
     const id = pane.tabOrder[index];
     if (id && (chip.offsetLeft < left || chip.offsetLeft + chip.offsetWidth > right)) {
@@ -889,8 +896,8 @@ function openOverflowMenu(pane: Pane, labels: Map<string, string>, anchorEl: HTM
     place: (box) => ({ x: Math.max(4, anchor.right - box.width), y: anchor.bottom }),
     placement: "block-end span-inline-start",
     region: "tab-overflow",
-    rows: ids.map((id) => ({
-      checked: (id === pane.activeTabId ? "true" : "false") as "true" | "false",
+    rows: ids.map((id): MenuRowProjection => ({
+      checked: id === pane.activeTabId ? "true" : "false",
       destructive: false,
       disabled: false,
       dividerAbove: false,
@@ -931,8 +938,8 @@ export function dismissTabContextMenu() {
  * where it lands (`content/draft-state.ts` says why), so the row offers the flip of what is true
  * now and {@link statedChecked} reads the current state back out of it for the checkmark.
  */
-function tabRowFacts(tab: Tab): Record<string, unknown> {
-  const facts: Record<string, unknown> = {};
+function tabRowFacts(tab: Tab): CommandArgValues {
+  const facts: CommandArgValues = {};
   if (collectionOfPath(tab.documentPath)) {
     facts.draft = !isDraftEntry(entryFields(tab));
   }
@@ -961,14 +968,14 @@ function tabRowFacts(tab: Tab): Record<string, unknown> {
  * already knows how to announce — and the five rows that carry no state stay plain `menuitem`s,
  * which `selects` on the old menu would have made impossible.
  */
-function statedChecked(args: Record<string, unknown>): "true" | "false" | undefined {
+function statedChecked(args: CommandArgValues): "true" | "false" | undefined {
   const entries = Object.entries(args);
-  const only = entries.length === 1 ? entries[0] : undefined;
-  if (!only || typeof only[1] !== "boolean") {
+  const value = entries.length === 1 ? entries[0]?.[1] : undefined;
+  if (!isBoolean(value)) {
     return undefined;
   }
   // The fact is the state the row would REACH, so the state it is in now is the negation.
-  return only[1] ? "false" : "true";
+  return value ? "false" : "true";
 }
 
 /**
@@ -989,13 +996,11 @@ function placedTabItems(tab: Tab): MenuRowProjection[] {
   const items: MenuRowProjection[] = [];
   let group: string | undefined;
   for (const command of registry.forPlacement("context/tab")) {
-    const schema = command.args as
-      | { properties?: Record<string, unknown>; required?: readonly string[] }
-      | undefined;
+    const schema = command.args;
     if (!(schema?.required ?? []).every((key) => key in facts)) {
       continue;
     }
-    const args: Record<string, unknown> = {};
+    const args: CommandArgValues = {};
     for (const key of Object.keys(schema?.properties ?? {})) {
       if (key in facts) {
         args[key] = facts[key];
@@ -1005,21 +1010,26 @@ function placedTabItems(tab: Tab): MenuRowProjection[] {
     ({ group } = command);
     const reason = registry.disabledReason(command.id);
     const checked = statedChecked(args);
-    items.push({
+    const row: Omit<MenuRowProjection, "disabled"> = {
       destructive: command.destructive === true,
       dividerAbove,
       id: command.id,
       title: command.title,
-      ...(checked === undefined ? {} : { checked }),
-      ...(reason === undefined
+    };
+    if (checked !== undefined) {
+      row.checked = checked;
+    }
+    items.push(
+      reason === undefined
         ? {
+            ...row,
             disabled: false,
             run: () => {
               void runReported(registry, command.id, args, "Tabs");
             },
           }
-        : { disabled: true, requires: reason }),
-    });
+        : { ...row, disabled: true, requires: reason },
+    );
   }
   return items;
 }
@@ -1270,7 +1280,7 @@ export function shouldWarnOnClose(tab: Tab): boolean {
   if (residue) {
     return true;
   }
-  const peersHere = state.peers.filter((p) => p.state?.focusedPath === tab.documentPath);
+  const peersHere = state.peers.filter((p) => p.state.focusedPath === tab.documentPath);
   return peersHere.length === 0;
 }
 

package/src/platform-errors.ts

@@ -14,6 +14,8 @@
 
 import { problemSlug } from "@jxsuite/protocol";
 import type { OfferedAction, RetryHint } from "@jxsuite/protocol";
+import { isJsonObject, isString } from "@jxsuite/schema/guards";
+import type { JsonValue } from "@jxsuite/schema/types";
 
 export interface PlatformErrorInfo {
   code?: string;
@@ -32,36 +34,44 @@ const RETRY_HINTS = new Set<string>(["reload", "repeat", "none"]);
  * The offered actions a wire value holds, each one checked: an action needs an `id` and a `label`
  * to be drawn at all, and anything else it carries is kept only when it has the right type. A
  * malformed entry is dropped rather than drawn as a button that does nothing.
+ *
+ * A typed `OfferedAction[]` is accepted too, and checked the same way: it is what a response body
+ * cast to its protocol type holds, and nothing has verified that cast.
  */
-export function offeredActions(value: unknown): OfferedAction[] {
+export function offeredActions(
+  value: JsonValue | readonly OfferedAction[] | undefined,
+): OfferedAction[] {
   if (!Array.isArray(value)) {
     return [];
   }
-  return value.flatMap((entry): OfferedAction[] => {
-    const raw = entry as Partial<Record<keyof OfferedAction, unknown>> | null;
-    if (
-      !raw ||
-      typeof raw.id !== "string" ||
-      !raw.id ||
-      typeof raw.label !== "string" ||
-      !raw.label
-    ) {
+  const entries: readonly (JsonValue | OfferedAction)[] = value;
+  return entries.flatMap((entry): OfferedAction[] => {
+    if (!isJsonObject(entry)) {
+      return [];
+    }
+    const { href, id, label, primary } = entry;
+    if (!isString(id) || !id || !isString(label) || !label) {
       return [];
     }
-    return [
-      {
-        id: raw.id,
-        label: raw.label,
-        ...(typeof raw.href === "string" && raw.href ? { href: raw.href } : {}),
-        ...(raw.primary === true ? { primary: true } : {}),
-      },
-    ];
+    const action: OfferedAction = { id, label };
+    if (isString(href) && href) {
+      action.href = href;
+    }
+    if (primary === true) {
+      action.primary = true;
+    }
+    return [action];
   });
 }
 
+/** Whether a value names one of the retry hints this client knows. */
+function isRetryHint(value: JsonValue | undefined): value is RetryHint {
+  return isString(value) && RETRY_HINTS.has(value);
+}
+
 /** The retry hint a wire value names, or undefined when it names none we know. */
-export function retryHint(value: unknown): RetryHint | undefined {
-  return typeof value === "string" && RETRY_HINTS.has(value) ? (value as RetryHint) : undefined;
+export function retryHint(value: JsonValue | undefined): RetryHint | undefined {
+  return isRetryHint(value) ? value : undefined;
 }
 
 /**
@@ -74,33 +84,37 @@ function normalizeCode(value: string): string {
 }
 
 /** Machine-readable fields carried by a thrown platform error (empty object when none). */
-export function platformErrorInfo(error: unknown): PlatformErrorInfo {
-  if (!error || typeof error !== "object") {
+export function platformErrorInfo(cause: unknown): PlatformErrorInfo {
+  /* An Error carrying the members an adapter assigned onto it passes as a JSON object here: every
+     member below is read through a check that accepts any value, so nothing trusts that typing. */
+  if (!isJsonObject(cause)) {
     return {};
   }
-  const { actions, code, heading, installUrl, retry, type } = error as {
-    actions?: unknown;
-    code?: unknown;
-    heading?: unknown;
-    installUrl?: unknown;
-    retry?: unknown;
-    type?: unknown;
-  };
-  const hint = retryHint(retry);
+  const { actions, code, heading, installUrl, retry, type } = cause;
+  const info: PlatformErrorInfo = {};
   // A problem type wins over a legacy code: it is the shape the backend is migrating toward.
-  const derived = problemSlug(type) ?? (typeof code === "string" ? normalizeCode(code) : null);
-  return {
-    ...(derived === null ? {} : { code: derived }),
-    ...(typeof installUrl === "string" ? { installUrl } : {}),
-    ...(actions === undefined ? {} : { actions: offeredActions(actions) }),
-    ...(typeof heading === "string" && heading ? { heading } : {}),
-    ...(hint === undefined ? {} : { retry: hint }),
-  };
+  const derived = problemSlug(type) ?? (isString(code) ? normalizeCode(code) : null);
+  if (derived !== null) {
+    info.code = derived;
+  }
+  if (isString(installUrl)) {
+    info.installUrl = installUrl;
+  }
+  if (actions !== undefined) {
+    info.actions = offeredActions(actions);
+  }
+  if (isString(heading) && heading) {
+    info.heading = heading;
+  }
+  if (isRetryHint(retry)) {
+    info.retry = retry;
+  }
+  return info;
 }
 
 /** The GitHub-App install link when the error is the structured needs-installation 403. */
-export function installUrlOf(error: unknown): string | null {
-  const info = platformErrorInfo(error);
+export function installUrlOf(cause: unknown): string | null {
+  const info = platformErrorInfo(cause);
   return info.code === "needs-installation-access" && info.installUrl ? info.installUrl : null;
 }
 
@@ -108,6 +122,6 @@ export function installUrlOf(error: unknown): string | null {
  * True when the error is an `action-required` refusal (HTTP 403, desktop.md §10.4) — whether the
  * backend sent the problem type or the legacy `action_required` code.
  */
-export function isActionRequired(error: unknown): boolean {
-  return platformErrorInfo(error).code === "action-required";
+export function isActionRequired(cause: unknown): boolean {
+  return platformErrorInfo(cause).code === "action-required";
 }

package/src/platform.ts

@@ -18,6 +18,7 @@
  * without ever calling the registrar, and this is the seam both paths share.
  */
 
+import { isFunction, isNonNullObject, isString } from "@jxsuite/schema/guards";
 import type { StudioPlatform } from "./types";
 
 /** What a launcher's boot module recorded when its adapter could not be constructed. */
@@ -42,14 +43,16 @@ export interface LauncherSignal {
   error?: LauncherBootError | undefined;
 }
 
-const g = globalThis as unknown as {
-  __jxPlatform?: StudioPlatform;
-  __jxLauncher?: LauncherSignal;
-};
+declare global {
+  /** The registered adapter, set by `registerPlatform` or pre-registered by a launcher bundle. */
+  var __jxPlatform: StudioPlatform | undefined;
+  /** The launcher's boot signal (spec/desktop.md §3.3), when a launcher announced itself. */
+  var __jxLauncher: LauncherSignal | undefined;
+}
 
 /** @param {StudioPlatform} platform */
 export function registerPlatform(platform: StudioPlatform) {
-  g.__jxPlatform = platform;
+  globalThis.__jxPlatform = platform;
 }
 
 /**
@@ -58,13 +61,12 @@ export function registerPlatform(platform: StudioPlatform) {
  * Idempotent, so an error recorded by the first announcer survives a second call.
  */
 export function announceLauncher(): LauncherSignal {
-  g.__jxLauncher ??= {};
-  return g.__jxLauncher;
+  return (globalThis.__jxLauncher ??= {});
 }
 
 /** The launcher signal, when a launcher's boot module announced itself in this window. */
 export function launcherSignal(): LauncherSignal | undefined {
-  return g.__jxLauncher;
+  return globalThis.__jxLauncher;
 }
 
 // ─── In-flight accounting ─────────────────────────────────────────────────────
@@ -102,6 +104,39 @@ function leave(method: string): void {
   }
 }
 
+/** A promise-like result, recognised the way `await` recognises one: by a callable `then`. */
+function isThenable(value: unknown): value is PromiseLike<unknown> {
+  return (isNonNullObject(value) || isFunction(value)) && "then" in value && isFunction(value.then);
+}
+
+/**
+ * One adapter method, wrapped so each call whose result is a promise counts as in flight under
+ * `method` until that promise settles. Any other result is returned untouched.
+ *
+ * The arguments are `never[]` because the wrapper is reached through the proxy, whose callers are
+ * typed by the member's own StudioPlatform signature; it relays whatever they pass, unread.
+ */
+function countCalls<R>(
+  method: string,
+  member: (...args: never[]) => R,
+  adapter: StudioPlatform,
+): (...args: never[]) => R {
+  return (...args: never[]): R => {
+    const result = member.apply(adapter, args);
+    if (!isThenable(result)) {
+      return result;
+    }
+    enter(method);
+    const settle = () => {
+      leave(method);
+    };
+    // Both arms: a rejected platform call is a call that FINISHED. Leaving it counted would
+    // Wedge every later `idle()` behind an error the caller already handled.
+    result.then(settle, settle);
+    return result;
+  };
+}
+
 /**
  * Wrap an adapter so every promise-returning member is counted while it is outstanding.
  *
@@ -111,13 +146,20 @@ function leave(method: string): void {
  * derive `capability.*`, and a fresh closure per read would allocate on every predicate).
  */
 function countingPlatform(platform: StudioPlatform): StudioPlatform {
-  const wrappers = new Map<PropertyKey, { raw: unknown; wrapper: unknown }>();
+  const wrappers = new Map<
+    string,
+    { raw: StudioPlatform[keyof StudioPlatform]; wrapper: unknown }
+  >();
   return new Proxy(platform, {
     get(target, property) {
-      // `this` stays the raw adapter: a proxy receiver would re-enter this trap for every internal
-      // Property read the method makes, counting nothing and costing everything.
-      const value = Reflect.get(target, property) as unknown;
-      if (typeof value !== "function" || typeof property !== "string") {
+      /* `this` stays the raw adapter: a proxy receiver would re-enter this trap for every internal
+         property read the method makes, counting nothing and costing everything.
+         SAFETY: a get trap is asked for any key, not only the ones StudioPlatform declares (`then`
+         when the proxy is awaited, inherited `toString`, symbols). An undeclared key reads as
+         undefined or an Object.prototype member, which the checks below relay untouched or wrap
+         exactly as they would a declared method, so the keyof claim never reaches a caller. */
+      const value = target[property as keyof StudioPlatform];
+      if (!isFunction(value) || !isString(property)) {
         return value;
       }
       // Keyed by the FUNCTION, not just the name: an adapter whose method is replaced later (a
@@ -127,21 +169,7 @@ function countingPlatform(platform: StudioPlatform): StudioPlatform {
       if (cached && cached.raw === value) {
         return cached.wrapper;
       }
-      const method = property;
-      const wrapper = (...args: unknown[]): unknown => {
-        const result = (value as (...a: unknown[]) => unknown).apply(target, args);
-        if (typeof (result as PromiseLike<unknown> | null)?.then !== "function") {
-          return result;
-        }
-        enter(method);
-        const settle = () => {
-          leave(method);
-        };
-        // Both arms: a rejected platform call is a call that FINISHED. Leaving it counted would
-        // Wedge every later `idle()` behind an error the caller already handled.
-        (result as PromiseLike<unknown>).then(settle, settle);
-        return result;
-      };
+      const wrapper = countCalls<ReturnType<typeof value>>(property, value, target);
       wrappers.set(property, { raw: value, wrapper });
       return wrapper;
     },
@@ -153,7 +181,7 @@ let counted: { raw: StudioPlatform; wrapped: StudioPlatform } | null = null;
 
 /** @returns {StudioPlatform} */
 export function getPlatform() {
-  const raw = g.__jxPlatform;
+  const raw = globalThis.__jxPlatform;
   if (!raw) {
     throw new Error("No platform registered. Call registerPlatform() before starting Studio.");
   }
@@ -165,5 +193,5 @@ export function getPlatform() {
 
 /** @returns {boolean} */
 export function hasPlatform() {
-  return g.__jxPlatform != null;
+  return globalThis.__jxPlatform != null;
 }