@jxsuite/studio 6.1.1 → 8.0.0

package/src/files/new-file-name.ts

@@ -0,0 +1,156 @@
+/**
+ * The rules a new file's name is held to, with no dialog and no write attached.
+ *
+ * `createFileIn` (`files/files.ts`) used to keep these inside one closure over its prompt, which
+ * was right while the prompt was the only creation flow there was. Add new (`create/add-new.ts`,
+ * `specs/studio.md` §9.1.1) composes a name the same way and must refuse the same things — a blank
+ * name, a name that escapes the destination, a name that is already taken — and a second copy of
+ * those rules would disagree with the first the first time either was fixed. So the composing and
+ * the judging live here, DOM-free, and both flows call them; only the write, and what each flow
+ * does around it, differs.
+ *
+ * Nothing here lists a directory. The caller supplies the `taken` names it listed, because when
+ * that listing happens is the caller's concern: before the prompt opens for New File, and once per
+ * destination directory for Add new, whose destination moves as the reader types.
+ *
+ * @docs studio/interface
+ */
+
+/**
+ * The picker row meaning "I will type the whole name myself".
+ *
+ * It is what keeps the format picker from being a cage. `New File…` is the only generic
+ * file-creation affordance in Studio and both backends create intermediate directories on write, so
+ * without this row `styles/main.css`, `public/robots.txt`, `.gitignore` and a `credits.txt` beside
+ * a collection's images all become uncreatable — and the picker would have taken away more than it
+ * gave. The picker stays the authority on the extension; this is one of its answers.
+ */
+export const OTHER_FORMAT = "__other__";
+
+/** How the extension of a new file is settled. */
+export type FormatChoice =
+  /** Picker over every creatable format, plus Other…. The field is a NAME, taken verbatim. */
+  | { kind: "choose"; defaultExt?: string; docKind?: "page" | "component" | "content" }
+  /**
+   * Picker holding ONE format, plus Other… — the collection's own extension. The field is a NAME.
+   * `because` is the sentence a refusal quotes when Other… would smuggle a foreign document in.
+   */
+  | { kind: "locked"; ext: string; because: string }
+  /** No picker. The field is a DISPLAY NAME, slugified, and `ext` is appended. */
+  | { kind: "fixed"; ext: string };
+
+/** A display name, reduced to a file stem. Lowercase by design: this is a slug. */
+export function slugify(input: string): string {
+  return input
+    .trim()
+    .toLowerCase()
+    .replaceAll(/\s+/g, "-")
+    .replaceAll(/[^a-z\d-]/g, "");
+}
+
+/** The extension of a file name, including the dot, or `""`. */
+export function extensionOfName(name: string): string {
+  const dot = name.lastIndexOf(".");
+  return dot > 0 ? name.slice(dot) : "";
+}
+
+/**
+ * The file name a field value and a pick compose to — three modes, not two.
+ *
+ * The verbatim STEM mode is not a convenience. The slugifier lowercases and strips everything
+ * outside `[a-z0-9-]`, which turns `[slug]` into `slug` — and eight shipped starters carry
+ * `pages/[slug].json`, `[sku].json`, `[...slug].json`. A picker that slugified would make a dynamic
+ * route uncreatable and would say nothing about it.
+ *
+ * @param input What the reader typed.
+ * @param picked The picker's value: an extension, {@link OTHER_FORMAT}, or `""` with no picker.
+ * @param choice How the extension is settled; absent takes the whole name verbatim.
+ */
+export function composeNewFileName(input: string, picked: string, choice?: FormatChoice): string {
+  const trimmed = input.trim();
+  if (choice === undefined || picked === OTHER_FORMAT) {
+    return trimmed;
+  }
+  if (choice.kind === "fixed") {
+    const slug = slugify(trimmed);
+    return slug === "" ? "" : `${slug}${choice.ext}`;
+  }
+  return trimmed.toLowerCase().endsWith(picked.toLowerCase()) ? trimmed : `${trimmed}${picked}`;
+}
+
+/** What a name is judged against: where it is going, and what is already there. */
+export interface NewFileNameCheck {
+  /** Destination directory, project-relative. `"."` is the project root. */
+  dir: string;
+  choice?: FormatChoice | undefined;
+  /** The destination's entries, LOWER-CASED: APFS and NTFS compare without case, and so does this. */
+  taken: ReadonlySet<string>;
+  /** Extensions that are documents, lower-cased (`knownDocumentExtensions()`). */
+  known?: ReadonlySet<string>;
+  /** The picker's rows, for naming a pick in a refusal. */
+  rows?: readonly { label: string; value: string }[] | null;
+}
+
+/**
+ * The refusal a name earns, or `""` when it is usable.
+ *
+ * In order: blank, a display name that slugifies to nothing, a path that starts or ends with a
+ * slash, a `..` segment, a subfolder where the field is a name rather than a whole file name, an
+ * extension that contradicts the pick, a document smuggled through Other… past a collection's lock,
+ * and finally a name already taken in the destination. The first that applies is the sentence.
+ *
+ * @param value What the reader typed.
+ * @param picked The picker's value, as {@link composeNewFileName} takes it.
+ * @param check The destination and what it already holds.
+ */
+export function validateNewFileName(
+  value: string,
+  picked: string,
+  check: NewFileNameCheck,
+): string {
+  const { choice, dir, known = new Set<string>(), rows = null, taken } = check;
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return choice?.kind === "fixed" ? "Enter a name." : "Enter a file name.";
+  }
+  if (choice?.kind === "fixed" && slugify(trimmed) === "") {
+    return "Enter at least one letter or number.";
+  }
+  const normalized = trimmed.replaceAll("\\", "/");
+  if (normalized.startsWith("/") || normalized.endsWith("/")) {
+    return "Enter a name, not a path that starts or ends with a slash.";
+  }
+  if (normalized.split("/").includes("..")) {
+    return "A name cannot step outside the destination folder.";
+  }
+  // A slash is the tree's ONLY way to make a directory — both backends create them on write — so
+  // It is allowed exactly where the field is a whole file name, and refused where it is a name.
+  if (normalized.includes("/") && choice !== undefined && picked !== OTHER_FORMAT) {
+    return `Pick Other… to create a file in a subfolder of ${dir === "." ? "the project root" : dir}.`;
+  }
+  /* A name whose extension MATCHES the pick is fine and is composed once, never doubled;
+     refusing every trailing extension would reject this dialog's own `untitled.json` default.
+     A name ending in an extension no format claims is a stem that happens to have a dot. */
+  const typedExt = extensionOfName(normalized);
+  if (
+    picked !== "" &&
+    picked !== OTHER_FORMAT &&
+    typedExt !== "" &&
+    typedExt.toLowerCase() !== picked.toLowerCase() &&
+    known.has(typedExt.toLowerCase())
+  ) {
+    const label = rows?.find((row) => row.value === picked)?.label ?? picked;
+    return `You picked ${label}; this name ends in ${typedExt}.`;
+  }
+  if (choice?.kind === "locked" && picked === OTHER_FORMAT) {
+    const foreign = typedExt !== "" && typedExt.toLowerCase() !== choice.ext.toLowerCase();
+    if (foreign && known.has(typedExt.toLowerCase())) {
+      return choice.because;
+    }
+  }
+  /* No emptiness check here: every way `composeNewFileName` can answer "" is already refused
+     above — a blank field by the first rule, a display name that slugifies to nothing by the
+     second. */
+  const candidate = composeNewFileName(value, picked, choice);
+  return taken.has(candidate.toLowerCase()) ? `${candidate} already exists in ${dir}/.` : "";
+}

package/src/files/serialize-document.ts

@@ -20,6 +20,7 @@ import {
   loadFormats,
 } from "../format/format-host";
 import { serializeJson } from "@jxsuite/schema/json-layout";
+import { restoreBareRepeaters } from "../tabs/bare-repeaters";
 import type { Tab } from "../tabs/tab";
 
 /**
@@ -40,15 +41,19 @@ export async function serializeDocument(tab: Tab): Promise<string> {
   await loadFormats();
   const sourceFormat = formatByName(tab.doc.sourceFormat);
   if (sourceFormat?.capabilities.serialize) {
-    const fm = tab.doc.content?.frontmatter || {};
+    const fm = tab.doc.content.frontmatter;
     const doc = tab.doc.document;
     const fullDoc = { ...fm, ...doc, children: doc.children ?? [] };
-    return formatSerialize(sourceFormat.name, fullDoc, { mode: "roundtrip" });
+    // The text the file was read as, so what the author did not edit keeps its own spelling.
+    return formatSerialize(sourceFormat.name, fullDoc, {
+      mode: "roundtrip",
+      ...(tab.doc.source !== null && { source: tab.doc.source }),
+    });
   }
   if (tab.doc.mode === "content") {
     const format = defaultContentFormat();
     if (format) {
-      const fm = tab.doc.content?.frontmatter ?? {};
+      const fm = tab.doc.content.frontmatter;
       const hasFrontmatter = Object.keys(fm).length > 0;
       const fullDoc = { ...fm, ...tab.doc.document };
       return formatSerialize(format.name, fullDoc, {
@@ -62,6 +67,11 @@ export async function serializeDocument(tab: Tab): Promise<string> {
      a blank line sits, which characters were escaped — and it is null for a document with no JSON
      source, where every object expands and every array is laid by fit: the formatter's own answer
      for stringified output. Either way the text ends with one newline, as every formatted file
-     does. */
-  return serializeJson(tab.doc.document, tab.doc.layout ?? null);
+     does. A repeater the file wrote as a node's whole `children` is written that way again
+     (`tabs/bare-repeaters.ts`), so the member form the editor works in never reaches the disk —
+     which is also what keeps the layout's pointers, taken from the file's own text, lined up. */
+  return serializeJson(
+    restoreBareRepeaters(tab.doc.document, tab.doc.bareRepeaters ?? null),
+    tab.doc.layout ?? null,
+  );
 }

package/src/format/constraints.ts

@@ -84,7 +84,7 @@ export function createNestingValidator(elements?: ElementsHints): NestingValidat
  *
  * Returned as a plain object because it crosses to the canvas frame with the render message.
  */
-export function formatEditableVerdicts(elements?: ElementsHints): Record<string, boolean> {
+export function formatEditableVerdicts(elements?: ElementsHints) {
   const verdicts: Record<string, boolean> = {};
   for (const [tag, rule] of Object.entries(elements?.nesting ?? {})) {
     // "_root" is the document itself, not an element.

package/src/format/convert-file.ts

@@ -29,6 +29,10 @@ import {
 import { convertTargetExtensions, convertTargets } from "./format-choices";
 import { parseJsonDocument, serializeJson } from "@jxsuite/schema/json-layout";
 import type { JsonLayout } from "@jxsuite/schema/json-layout";
+import { isString } from "@jxsuite/schema/guards";
+import type { JsonValue, JxMutableNode } from "@jxsuite/schema/types";
+import type { CommandArgValues } from "../commands/command-args";
+import type { FormatFrontmatter } from "./format-host";
 import type { AnyCommand, CommandRegistry } from "../commands/registry";
 
 /** What a conversion will do, resolved in full before the reader is asked to confirm it. */
@@ -72,14 +76,17 @@ function withExtension(path: string, ext: string): string {
 async function readDocument(
   path: string,
   source: string,
-): Promise<{ document: Record<string, unknown>; frontmatter: Record<string, unknown> }> {
+): Promise<{ document: JxMutableNode; frontmatter: FormatFrontmatter }> {
   const { formatForPath } = await import("./format-host");
   if (formatForPath(path)) {
     const { parseSourceForPath } = await import("../files/file-ops");
     const parsed = await parseSourceForPath(path, source);
     return { document: parsed.document, frontmatter: parsed.frontmatter };
   }
-  return { document: JSON.parse(source) as Record<string, unknown>, frontmatter: {} };
+  /* SAFETY: a path no format claims is a `.json` document in pages/ or components/ (the only files
+     `convertTargets` offers a conversion for), and that file's schema requires a top-level object;
+     `JSON.parse` without a reviver yields a JSON value, so the object is a Jx document. */
+  return { document: JSON.parse(source) as JxMutableNode, frontmatter: {} };
 }
 
 /**
@@ -94,8 +101,8 @@ async function readDocument(
  */
 async function writeDocument(
   targetExt: string,
-  document: Record<string, unknown>,
-  frontmatter: Record<string, unknown>,
+  document: JxMutableNode,
+  frontmatter: FormatFrontmatter,
 ): Promise<string> {
   const merged = { ...frontmatter, ...document };
   if (targetExt === ".json") {
@@ -194,7 +201,9 @@ export async function buildPlan(
        errors, which is indistinguishable from a valid document. Claiming validity on the strength of
        a schema that was never compiled is the "never render 0" defect one layer down. */
     const { validateDocOrNull } = await import("../services/jx-validate");
-    const errors = await validateDocOrNull(JSON.parse(text));
+    /* SAFETY: `text` is what `serializeJson` just wrote, and `JSON.parse` without a reviver yields
+       a JSON value. */
+    const errors = await validateDocOrNull(JSON.parse(text) as JsonValue);
     if (errors === null) {
       lines.push(
         "The result could not be checked against the document schema — that is not the same as " +
@@ -292,7 +301,9 @@ export async function convertFile(path: string, targetExt?: string): Promise<str
 
   let original: string;
   try {
-    original = (await platform.readFile(path)) ?? "";
+    // The read crosses the PAL's wire, which can answer without a `content` field: read that as empty.
+    const read = await platform.readFile(path);
+    original = isString(read) ? read : "";
   } catch (error) {
     return fail(`Could not read ${path}.`, errorMessage(error));
   }
@@ -373,8 +384,8 @@ async function rebuildTab(from: string, to: string, text: string): Promise<void>
   const { formatForPath } = await import("./format-host");
   renameTab(from, to, to);
   const format = formatForPath(to);
-  let document: Record<string, unknown>;
-  let frontmatter: Record<string, unknown> | undefined;
+  let document: JxMutableNode;
+  let frontmatter: FormatFrontmatter | undefined;
   // The layout of the JSON just written, as every other JSON reader records it (`files/files.ts`,
   // `files/file-ops.ts`): the text is the serializer's own, so the record says what a layout-less
   // Write would do anyway — but the tab reads its file rather than assuming it.
@@ -392,14 +403,17 @@ async function rebuildTab(from: string, to: string, text: string): Promise<void>
     // Points at the file, and reopening it is one click.
     return;
   }
-  openTab({
+  const options: Parameters<typeof openTab>[0] = {
     document,
     documentPath: to,
-    ...(frontmatter === undefined ? {} : { frontmatter }),
     id: to,
     layout,
     sourceFormat: format?.name ?? null,
-  });
+  };
+  if (frontmatter !== undefined) {
+    options.frontmatter = frontmatter;
+  }
+  openTab(options);
 }
 
 const CANNOT_CONVERT =
@@ -499,8 +513,8 @@ export function fileFormatCommands(): AnyCommand[] {
       undo: "none",
       /* No `aiTool`, by studio-ui-guidelines.md §12.4's second deletion rule: `run` awaits a
          confirm dialog the person answers. */
-      run: async (_ctx, args: Record<string, unknown>) => {
-        const target = typeof args.format === "string" ? args.format : undefined;
+      run: async (_ctx, args: CommandArgValues) => {
+        const target = isString(args.format) ? args.format : undefined;
         await convertFile(
           stringArg("file.convertFormat", args, "source"),
           ...(target === undefined ? [] : [target]),

package/src/format/format-choices.ts

@@ -11,6 +11,7 @@
  * context menu is built during a render and cannot await anything.
  */
 
+import { isString } from "@jxsuite/schema/guards";
 import { collectionForFile } from "../content/collection-match";
 import { documentExtensions, formatByExtension, formatForPath, getFormats } from "./format-host";
 import { projectState } from "../store";
@@ -76,7 +77,7 @@ function declaresDocumentKind(kinds: readonly string[]): boolean {
  */
 function isLayoutPath(path: string): boolean {
   const declared = projectState?.projectConfig?.layout;
-  if (typeof declared !== "string") {
+  if (!isString(declared)) {
     return false;
   }
   return normalize(declared).toLowerCase() === normalize(path).toLowerCase();

package/src/format/format-host.ts

@@ -9,8 +9,15 @@
 
 import { setProjectSchemasForMonaco } from "../services/monaco-lazy";
 import { getPlatform } from "../platform";
-import type { ExtensionCatalogEntry, ExtensionsInfo } from "../types";
-import type { JxMutableNode } from "@jxsuite/schema/types";
+import type {
+  ExtensionCatalogEntry,
+  ExtensionsInfo,
+  FormatActionRequest,
+  ProjectSchemasResponse,
+  StudioPlatform,
+} from "../types";
+import { isString } from "@jxsuite/schema/guards";
+import type { JxDocumentValue, JxMutableNode } from "@jxsuite/schema/types";
 
 export interface StudioFormatHints {
   icon?: string;
@@ -25,6 +32,10 @@ export interface StudioFormatHints {
     inline?: string[];
     void?: string[];
     textOnly?: string[];
+    /**
+     * Per-parent child rules. The registry arrives over the wire unvalidated, so a rule may be a
+     * JSON `null`, which every reader treats as a tag the format leaves undeclared.
+     */
     nesting?: Record<
       string,
       {
@@ -32,10 +43,9 @@ export interface StudioFormatHints {
         inline?: boolean;
         directive?: boolean;
         only?: string[];
-      }
+      } | null
     >;
   };
-  [key: string]: unknown;
 }
 
 export interface StudioFormat {
@@ -57,10 +67,11 @@ export function loadFormats(): Promise<StudioFormat[]> {
   if (!_loaded) {
     _loaded = (async () => {
       try {
-        const platform = getPlatform() as {
-          listFormats?: () => Promise<StudioFormat[]>;
-        };
-        _formats = (await platform.listFormats?.()) ?? [];
+        const platform = getPlatform();
+        /* SAFETY: every backend's formats route serializes its format registry as the records this
+           Module declares (`StudioFormat`); the PAL types the payload `unknown[]` only because this
+           Module, not `types.ts`, owns that shape. */
+        _formats = ((await platform.listFormats?.()) as StudioFormat[] | undefined) ?? [];
       } catch {
         _formats = [];
       }
@@ -100,9 +111,7 @@ export function loadExtensions(): Promise<ExtensionsInfo[]> {
   if (!_extensionsLoaded) {
     _extensionsLoaded = (async () => {
       try {
-        const platform = getPlatform() as {
-          listExtensions?: () => Promise<ExtensionsInfo[]>;
-        };
+        const platform = getPlatform();
         _extensions = (await platform.listExtensions?.()) ?? [];
       } catch {
         _extensions = [];
@@ -144,9 +153,7 @@ export function loadExtensionCatalog(): Promise<ExtensionCatalogEntry[]> {
   if (!_catalogLoaded) {
     _catalogLoaded = (async () => {
       try {
-        const platform = getPlatform() as {
-          listExtensionCatalog?: () => Promise<ExtensionCatalogEntry[]>;
-        };
+        const platform = getPlatform();
         _catalog = (await platform.listExtensionCatalog?.()) ?? [];
       } catch {
         _catalog = [];
@@ -180,10 +187,10 @@ export function setExtensionCatalog(catalog: ExtensionCatalogEntry[]) {
  * @param {object} platform - The studio platform (only `fetchProjectSchemas` is consulted)
  * @returns {Promise<void>} Resolves once both consumers have been updated
  */
-async function shareProjectSchemas(platform: {
-  fetchProjectSchemas?: () => Promise<{ project?: unknown; document?: unknown }>;
-}): Promise<void> {
-  let schemas: { project?: unknown; document?: unknown } | null = null;
+async function shareProjectSchemas(
+  platform: Pick<StudioPlatform, "fetchProjectSchemas">,
+): Promise<void> {
+  let schemas: ProjectSchemasResponse | null = null;
   try {
     schemas = (await platform.fetchProjectSchemas?.()) ?? null;
   } catch {
@@ -208,9 +215,7 @@ async function shareProjectSchemas(platform: {
  *
  * @param {object} platform - The studio platform (only `fetchProjectSchemas` is consulted here)
  */
-export function refreshExtensionUi(platform: {
-  fetchProjectSchemas?: () => Promise<{ project?: unknown; document?: unknown }>;
-}): void {
+export function refreshExtensionUi(platform: Pick<StudioPlatform, "fetchProjectSchemas">): void {
   void shareProjectSchemas(platform);
   // `installed` and `bundled` are per-project facts, so an install or a project switch can move
   // Them even when the shipped half has not changed.
@@ -279,15 +284,40 @@ export function documentExtensions(kind?: string): string[] {
   return [...exts];
 }
 
+/**
+ * The extensions the build routes under `pages/`: `.json`, and every extension a page format claims
+ * (`discoverPages` in `@jxsuite/compiler` walks with the same set). Waits for the registry, so a
+ * Markdown page is never judged unroutable because the formats had not landed yet.
+ */
+export async function routedPageExtensions(): Promise<string[]> {
+  await loadFormats();
+  return [".json", ...documentExtensions("page")];
+}
+
 /** The default format for new content documents (first content-kind serializer). */
 export function defaultContentFormat(): StudioFormat | undefined {
   return _formats.find((f) => f.capabilities.serialize && f.documentKinds.includes("content"));
 }
 
-async function formatAction(payload: Record<string, unknown>): Promise<unknown> {
-  const platform = getPlatform() as {
-    formatAction?: (payload: Record<string, unknown>) => Promise<unknown>;
-  };
+/** The options a format capability is invoked with. */
+export interface FormatActionOptions {
+  /** `"roundtrip"` asks the format to preserve what it can of the source's own spelling. */
+  mode?: string;
+  /** Whether the serializer writes a frontmatter block. */
+  frontmatter?: boolean;
+  /**
+   * The text the document was read from: a roundtrip serializer keeps the spelling of whatever did
+   * not change (`@jxsuite/parser`'s `source` option).
+   */
+  source?: string;
+}
+
+/**
+ * Send one request to the format route (POST /__studio/format, or the desktop RPC of the same
+ * name). A serialize request carries the caller's document through unchanged.
+ */
+async function formatAction(payload: FormatActionRequest): Promise<JxMutableNode | string> {
+  const platform = getPlatform();
   if (!platform.formatAction) {
     throw new Error("Platform does not support format actions");
   }
@@ -298,8 +328,11 @@ async function formatAction(payload: Record<string, unknown>): Promise<unknown>
 export async function formatParse(
   name: string,
   source: string,
-  options?: Record<string, unknown>,
+  options?: FormatActionOptions,
 ): Promise<JxMutableNode> {
+  /* SAFETY: a format class's `parse` capability returns the Jx document it built from the source —
+     The contract every format class implements (specs/extensions.md) — and nothing here inspects
+     It before `splitFormatDocument` reads its keys. */
   return (await formatAction({
     action: "parse",
     format: name,
@@ -308,12 +341,19 @@ export async function formatParse(
   })) as JxMutableNode;
 }
 
-/** Serialize a Jx document to source text via the named format's serialize capability. */
+/**
+ * Serialize a Jx document to source text via the named format's serialize capability.
+ *
+ * `doc` is relayed to the format class verbatim: the document merged with its frontmatter, whose
+ * open keys are whatever the format's own parser produced.
+ */
 export async function formatSerialize(
   name: string,
-  doc: Record<string, unknown>,
-  options?: Record<string, unknown>,
+  doc: JxMutableNode,
+  options?: FormatActionOptions,
 ): Promise<string> {
+  /* SAFETY: a format class's `serialize` capability returns the source text it wrote — the contract
+     Every format class implements (specs/extensions.md) — so the answer is a string. */
   return (await formatAction({
     action: "serialize",
     doc,
@@ -322,42 +362,47 @@ export async function formatSerialize(
   })) as string;
 }
 
+/** A document's frontmatter: the open keys of a Jx node, as a format's parser left them. */
+export type FormatFrontmatter = Record<string, JxDocumentValue | undefined>;
+
+/** What {@link splitFormatDocument} makes of a parsed format document. */
+export interface SplitFormatDocument {
+  document: JxMutableNode;
+  frontmatter: FormatFrontmatter;
+  mode: "component" | "content";
+}
+
 /**
  * Split a parsed format document into { document, frontmatter, mode } per the format's
  * `$studio.documentMode` hints. Component documents (e.g. a frontmatter `tagName` with a hyphen)
  * keep their full shape; content documents separate frontmatter metadata from the body children.
  */
-export function splitFormatDocument(format: StudioFormat | undefined, doc: JxMutableNode) {
+export function splitFormatDocument(
+  format: StudioFormat | undefined,
+  doc: JxMutableNode,
+): SplitFormatDocument {
   const hints = format?.studio?.documentMode;
   const componentWhen = hints?.componentWhen;
   if (componentWhen?.frontmatterKey) {
     const value = doc[componentWhen.frontmatterKey];
     const pattern = componentWhen.matches ? new RegExp(componentWhen.matches) : /./;
-    if (typeof value === "string" && pattern.test(value)) {
-      return {
-        document: doc,
-        frontmatter: {} as Record<string, unknown>,
-        mode: "component",
-      };
+    if (isString(value) && pattern.test(value)) {
+      return { document: doc, frontmatter: {}, mode: "component" };
     }
   }
   if (hints?.default === "component") {
-    return {
-      document: doc,
-      frontmatter: {} as Record<string, unknown>,
-      mode: "component",
-    };
+    return { document: doc, frontmatter: {}, mode: "component" };
   }
 
   // Content document — children form the root-level body; other keys are frontmatter
-  const children = (doc.children as unknown[]) ?? [];
-  if (children.length === 0) {
+  const children = doc.children ?? [];
+  if (Array.isArray(children) && children.length === 0) {
     children.push({ children: [], tagName: "p" });
   }
 
   const documentKeys = new Set(["state", "imports"]);
-  const contentDoc: Record<string, unknown> = { children };
-  const frontmatter: Record<string, unknown> = {};
+  const contentDoc: JxMutableNode = { children };
+  const frontmatter: FormatFrontmatter = {};
   for (const [key, value] of Object.entries(doc)) {
     if (key === "children") {
       continue;
@@ -369,9 +414,5 @@ export function splitFormatDocument(format: StudioFormat | undefined, doc: JxMut
     }
   }
 
-  return {
-    document: contentDoc as JxMutableNode,
-    frontmatter,
-    mode: "content",
-  };
+  return { document: contentDoc, frontmatter, mode: "content" };
 }

package/src/github/github-auth-status.ts

@@ -18,6 +18,14 @@
 
 const STORAGE_KEY = "jx_github_token";
 
+/**
+ * The GitHub OAuth app every Jx sign-in authorizes against: the browser's device flow in
+ * `github-auth.ts`, and the desktop launcher's RFC 8252 loopback redirect
+ * (`packages/desktop/src/github-signin.ts`). Here, in the module with no UI dependency, because the
+ * launcher's main process imports it too.
+ */
+export const GITHUB_OAUTH_CLIENT_ID = "Ov23liYVlMFpgjOEPXJH";
+
 /**
  * The desktop launcher's RFC 8252 sign-in, when this build is running inside one.
  *
@@ -30,13 +38,29 @@ export interface NativeGithubAuth {
   status: () => Promise<{ stored: boolean }>;
 }
 
-export function nativeAuth(): NativeGithubAuth | null {
+/**
+ * Whether the registered platform object carries a launcher's `githubAuth` member.
+ *
+ * Presence is the whole test, as it always was: the member is written only by a launcher's adapter
+ * (`packages/desktop/src/platform.ts`), which installs a {@link NativeGithubAuth}, and a browser
+ * build has no member at all.
+ */
+function carriesNativeAuth(platform: unknown): platform is { githubAuth: NativeGithubAuth } {
   return (
-    (globalThis as unknown as { __jxPlatform?: { githubAuth?: NativeGithubAuth } }).__jxPlatform
-      ?.githubAuth ?? null
+    typeof platform === "object" &&
+    platform !== null &&
+    "githubAuth" in platform &&
+    platform.githubAuth != null
   );
 }
 
+export function nativeAuth(): NativeGithubAuth | null {
+  // `globalThis` as a plain object: its declared type knows nothing of the launcher's slot.
+  const host: object = globalThis;
+  const platform = "__jxPlatform" in host ? host.__jxPlatform : undefined;
+  return carriesNativeAuth(platform) ? platform.githubAuth : null;
+}
+
 /**
  * The token the desktop store handed us this session.
  *