@jxsuite/studio 6.1.1 → 6.1.2

package/src/commands/live-context.ts

@@ -25,6 +25,7 @@
  * studio.ts, and lets a test state a context without standing up the app.
  */
 
+import { isFunction, isString } from "@jxsuite/schema/guards";
 import { resolveI18n } from "@jxsuite/schema/locale";
 import { componentRegistry } from "../files/components";
 import { getNodeAtPath, projectState } from "../store";
@@ -36,7 +37,7 @@ import { hasTyping } from "../tabs/typing";
 import { collabState } from "../collab/collab-state";
 
 import { canvasViewForMode, editorKindForMode, emptyContext } from "./context";
-import type { CommandContext, FocusRegion } from "./context";
+import type { CommandContext } from "./context";
 import type { StudioPlatform } from "../types";
 
 /** Elements that own the keyboard while focused. Matches the old listener's target test exactly. */
@@ -86,7 +87,7 @@ export interface LiveContextSources {
 
 /** `capability.*` is presence-of-method on the PAL — the check every call site does by hand today. */
 function capabilities(platform: StudioPlatform | null): CommandContext["capability"] {
-  const has = (key: keyof StudioPlatform) => typeof platform?.[key] === "function";
+  const has = (key: keyof StudioPlatform) => isFunction(platform?.[key]);
   return {
     dataRows: has("dataRows"),
     // The real member now, not the `codeService` stand-in it was minted against: the usage query is
@@ -161,18 +162,17 @@ export function createLiveContext(sources: LiveContextSources): () => CommandCon
     const selection = primarySelection(paths);
     if (selection) {
       const node = getNodeAtPath(tab!.doc.document, selection);
+      const tagName = node?.tagName;
       ctx.selection.count = paths.length;
       ctx.selection.paths = paths.map((path) => [...path]);
       // Every remaining fact describes the PRIMARY — the one node a single-target verb addresses —
       // Except `isRoot`, which is the batch's own gate: a batch containing the document element
       // Cannot be deleted or duplicated any more than that element could be on its own.
-      ctx.selection.kind = typeof node?.tagName === "string" ? node.tagName : "";
+      ctx.selection.kind = isString(tagName) ? tagName : "";
       // A path of fewer than two segments addresses the document element itself — the same test
       // `shortcuts.ts` spelled as `selection.length >= 2` at four separate call sites.
       ctx.selection.isRoot = paths.some((path) => path.length < 2);
-      ctx.selection.isComponentInstance = componentRegistry.some(
-        (c) => c.tagName === node?.tagName,
-      );
+      ctx.selection.isComponentInstance = componentRegistry.some((c) => c.tagName === tagName);
       ctx.selection.isRepeater = node?.$prototype === "Array";
     }
     // Layout chrome is NOT a document selection: the node is not in the open page at all.
@@ -187,7 +187,7 @@ export function createLiveContext(sources: LiveContextSources): () => CommandCon
        being typed into. The stack asks "is something being typed into"; a record asks "is the
        thing being typed into the page". */
     ctx.caret.inCanvas = sources.isCaretActive();
-    ctx.focus.region = shell.focusRegion as FocusRegion;
+    ctx.focus.region = shell.focusRegion;
     ctx.modal.open = sources.isModalOpen();
 
     if (tab) {

package/src/commands/reference.ts

@@ -17,6 +17,7 @@
  * between runs is a CI diff nobody can review.
  */
 
+import { isString } from "@jxsuite/schema/guards";
 import { formatChord, normalizeChord } from "./keymap";
 import { CATEGORIES } from "./levels";
 import type { KeybindingOverrides } from "./keymap";
@@ -83,7 +84,7 @@ function chordsOf(command: AnyCommand): string[] {
   if (!raw) {
     return [];
   }
-  return (typeof raw === "string" ? [raw] : [...raw]).map((chord) => normalizeChord(chord));
+  return (isString(raw) ? [raw] : [...raw]).map((chord) => normalizeChord(chord));
 }
 
 /**

package/src/commands/registry.ts

@@ -36,13 +36,12 @@ import { createKeymap } from "./keymap";
 import type { KeyChordEvent, Keymap, KeymapMatch } from "./keymap";
 import { checkRecordPlacements } from "./levels";
 import type { Category, KeyScope, Level, Placement } from "./levels";
+import { isFunction } from "@jxsuite/schema/guards";
 import { coerceArgs } from "./command-args";
+import type { CommandArgsSchema, CommandArgValues } from "./command-args";
 import { runReported } from "./run-reported";
 import type { CommandContext } from "./context";
 
-/** Arguments as they arrive from a palette prompt, an automation manifest step or an AI tool call. */
-export type CommandArgs = Record<string, unknown>;
-
 /** How an action's effect is undone — surfaced to the user before an agent runs it. */
 export type UndoScope = "document" | "project" | "none";
 
@@ -77,7 +76,7 @@ export interface Command<A = void> {
    * shot check's contract AND what {@link CommandRegistry.run} coerces the received record against
    * before `run` sees it (`command-args.ts`'s `coerceArgs`). One object, four readers.
    */
-  args?: object;
+  args?: CommandArgsSchema;
   /** Surfaces this command renders in. Defaults to `["palette"]`. */
   menus?: readonly Placement[];
   /** Menu ordering key: "1_clipboard", "3_structure", "9_danger". */
@@ -216,7 +215,7 @@ export interface CommandRegistry {
    * `RangeError` naming the argument when `args` does not fit the record's schema — synchronously,
    * before `run` is entered, whichever surface the call came from.
    */
-  run: (id: string, args?: CommandArgs) => void | Promise<void>;
+  run: (id: string, args?: CommandArgValues) => void | Promise<void>;
   /** The chord index, conflict-checked at registration. */
   keymap: Keymap;
   /** Resolve a keyboard event through a scope stack and run what it hits. */
@@ -254,7 +253,7 @@ function checkProjection(command: AnyCommand, toolNames: ReadonlyMap<string, str
       `command "${command.id}" aiTool name "${tool.name}" is already projected by "${claimant}"`,
     );
   }
-  if (typeof tool.report !== "function") {
+  if (!isFunction(tool.report)) {
     throw new TypeError(
       `command "${command.id}" declares aiTool without a report: a tool that can only say ` +
         `"done" is refused`,
@@ -270,8 +269,7 @@ function checkProjection(command: AnyCommand, toolNames: ReadonlyMap<string, str
      selector's `paths` property in FRONT of the record's own `args`, so a record that declares its
      own `paths` would have two definitions of one argument — the model would read the record's
      description and the bridge would hand the value to the selector. */
-  const properties = (command.args as { properties?: Record<string, unknown> } | undefined)
-    ?.properties;
+  const properties = command.args?.properties;
   if (command.level === "selection" && properties && Object.hasOwn(properties, "paths")) {
     throw new Error(
       `command "${command.id}" is selection-level and may not declare "paths": the assistant ` +
@@ -341,11 +339,11 @@ export function createCommandRegistry(options: CommandRegistryOptions): CommandR
       if (violations.length > 0) {
         throw new Error(`command "${command.id}" ${violations[0]!.message}`);
       }
-      checkProjection(command as AnyCommand, toolNames);
+      checkProjection(command, toolNames);
       // Chord conflicts throw from the keymap; do this LAST so a rejected record leaves the
       // Registry untouched in every failure mode — the tool name is claimed only after it.
       keymap.add(command);
-      commands.set(command.id, command as AnyCommand);
+      commands.set(command.id, command);
       if (command.aiTool) {
         toolNames.set(command.aiTool.name, command.id);
       }
@@ -404,6 +402,10 @@ export function createCommandRegistry(options: CommandRegistryOptions): CommandR
          their typed readers; `coerceArgs` dispatches to the same functions, so the two cannot
          disagree. A record with no `args` takes whatever it was handed, as it always has. */
       const coerced = command.args ? coerceArgs(id, command.args, args) : args;
+      /* SAFETY: a stored record is `Command<never>` because the map erases each record's own `A`.
+         The runtime contract for that erased `A` is the record's `args` schema, which `coerceArgs`
+         has just applied (every key its reader's return value, an undeclared key refused); a
+         record with no schema takes the caller's record as it always has. */
       return command.run(ctx, coerced as never);
     },
     keymap,

package/src/commands/run-reported.ts

@@ -55,7 +55,8 @@
 import { errorMessage } from "@jxsuite/schema/parse";
 import { notify } from "../services/notify";
 import { activeRegistry } from "./active-registry";
-import type { CommandArgs, CommandRegistry } from "./registry";
+import type { CommandArgValues } from "./command-args";
+import type { CommandRegistry } from "./registry";
 
 /**
  * Whether an error is one of the two REFUSAL shapes, whose message is written to be read whole.
@@ -64,10 +65,10 @@ import type { CommandArgs, CommandRegistry } from "./registry";
  * `handleKeyEvent`, and a value import back would close a cycle for one class whose constructor
  * sets exactly this name. `RangeError` is the shape `coerceArgs` and a `run` body refuse with.
  */
-function isRefusal(error: unknown): boolean {
+function isRefusal(cause: unknown): boolean {
   return (
-    error instanceof RangeError ||
-    (error instanceof Error && error.name === "CommandUnavailableError")
+    cause instanceof RangeError ||
+    (cause instanceof Error && cause.name === "CommandUnavailableError")
   );
 }
 
@@ -86,15 +87,15 @@ function isRefusal(error: unknown): boolean {
 export function runReported(
   registry: CommandRegistry,
   id: string,
-  args?: CommandArgs,
+  args?: CommandArgValues,
   source: string = id,
 ): Promise<void> {
-  const report = (error: unknown) => {
-    if (!isRefusal(error)) {
+  const report = (cause: unknown) => {
+    if (!isRefusal(cause)) {
       // A crash, not a refusal: the row below carries the sentence, the console keeps the stack.
-      console.error(`${source}: command "${id}" failed`, error);
+      console.error(`${source}: command "${id}" failed`, cause);
     }
-    notify.error(errorMessage(error), { key: `command.run:${id}`, source });
+    notify.error(errorMessage(cause), { key: `command.run:${id}`, source });
   };
   let result: void | Promise<void>;
   try {
@@ -114,7 +115,11 @@ export function runReported(
  * registry to refuse it, so there is no refusal to file. The resolved promise keeps the caller's
  * `void` honest either way.
  */
-export function runActiveReported(id: string, args?: CommandArgs, source?: string): Promise<void> {
+export function runActiveReported(
+  id: string,
+  args?: CommandArgValues,
+  source?: string,
+): Promise<void> {
   const registry = activeRegistry();
   return registry ? runReported(registry, id, args, source) : Promise.resolve();
 }

package/src/component-props.ts

@@ -11,8 +11,13 @@
  */
 
 import type { JsonValue } from "./types";
-import type { JxMutableNode } from "@jxsuite/schema/types";
-import { isPrivateStateKey } from "@jxsuite/schema/guards";
+import type {
+  JsonPrimitive,
+  JxMutableNode,
+  JxStateDefinition,
+  JxStateObject,
+} from "@jxsuite/schema/types";
+import { isNonNullObject, isPrivateStateKey, isString } from "@jxsuite/schema/guards";
 
 /** One editable prop row: the state key and its current default value (undefined = none). */
 export interface ComponentPropEntry {
@@ -22,7 +27,16 @@ export interface ComponentPropEntry {
 
 /** Whether the doc is a component definition (a custom-element root) rather than a page. */
 export function isComponentDoc(doc: JxMutableNode | null | undefined): boolean {
-  return typeof doc?.tagName === "string" && doc.tagName.includes("-");
+  const tagName = doc?.tagName;
+  return isString(tagName) && tagName.includes("-");
+}
+
+/** The object shapes a state entry can take: every `JxStateDefinition` but a primitive or array. */
+type StateEntryObject = Exclude<JxStateDefinition, JsonPrimitive | JsonValue[]>;
+
+/** Whether a state entry is one of its object shapes — a signal, a typed def, a naked object. */
+function isStateEntryObject(def: JxStateDefinition | undefined): def is StateEntryObject {
+  return isNonNullObject(def) && !Array.isArray(def);
 }
 
 /**
@@ -31,26 +45,20 @@ export function isComponentDoc(doc: JxMutableNode | null | undefined): boolean {
  * templates, or $prototype data sources (overriding those would clobber behavior, the boundPropKey
  * rule).
  */
-function propShape(def: unknown): "literal" | "signal" | null {
-  if (def === null || typeof def === "number" || typeof def === "boolean") {
-    return "literal";
-  }
-  if (typeof def === "string") {
-    return def.includes("${") ? null : "literal"; // Template strings render computed values.
-  }
-  if (Array.isArray(def)) {
-    return "literal";
+function propKind(def: JxStateDefinition | undefined): "literal" | "signal" | null {
+  if (def === undefined) {
+    return null;
   }
-  if (typeof def === "object") {
-    const d = def as Record<string, unknown>;
-    if (d.$expression || d.$compute || d.$prototype || d.$handler) {
+  if (isStateEntryObject(def)) {
+    if (def.$expression || def.$compute || def.$prototype || def.$handler) {
       return null;
     }
     // An expanded signal ({default}) or a typed prop def ({type}/schema keywords) seeds through
     // Its `default`; any other plain object is a Shape-1 naked value.
-    return "default" in d || "type" in d ? "signal" : "literal";
+    return "default" in def || "type" in def ? "signal" : "literal";
   }
-  return null;
+  // Null, numbers, booleans and arrays are naked literals. Template strings render computed values.
+  return isString(def) && def.includes("${") ? null : "literal";
 }
 
 /**
@@ -58,20 +66,20 @@ function propShape(def: unknown): "literal" | "signal" | null {
  * entries with their current default values (the CEM-export "field" subset).
  */
 export function componentPropEntries(doc: JxMutableNode | null | undefined): ComponentPropEntry[] {
-  const state = (doc?.state ?? {}) as Record<string, unknown>;
+  const state: Record<string, JxStateDefinition> = doc?.state ?? {};
   const out: ComponentPropEntry[] = [];
   for (const [name, def] of Object.entries(state)) {
     if (isPrivateStateKey(name)) {
       continue; // Private entries are not props (spec.md §5.6).
     }
-    const shape = propShape(def);
-    if (!shape) {
+    const kind = propKind(def);
+    if (!kind) {
       continue;
     }
-    const value =
-      shape === "signal"
-        ? ((def as { default?: JsonValue }).default as JsonValue | undefined)
-        : (def as JsonValue);
+    /* SAFETY: `propKind` refused every behavioral shape (expressions, computeds, `$prototype`
+       sources, handlers, template strings), so what is left is the document's plain data: a
+       literal entry IS the JSON value, and a signal entry is an object whose `default` is one. */
+    const value = kind === "signal" ? (def as { default?: JsonValue }).default : (def as JsonValue);
     out.push({ name, value });
   }
   return out;
@@ -87,19 +95,27 @@ export function substitutePreviewProps(
   renderDoc: JxMutableNode,
   props: Record<string, JsonValue>,
 ): JxMutableNode {
-  const state = { ...((renderDoc.state ?? {}) as Record<string, unknown>) };
+  const state = { ...renderDoc.state };
   let seeded = false;
   for (const [name, value] of Object.entries(props)) {
-    const shape = propShape(state[name]);
-    if (!shape) {
+    const current = state[name];
+    const kind = propKind(current);
+    if (!kind) {
       continue; // Unknown/behavioral entries are never overridden by a stale test value.
     }
-    state[name] =
-      shape === "signal" ? { ...(state[name] as Record<string, unknown>), default: value } : value;
+    /* SAFETY: `propKind` answers "signal" only for an object that carries `default` or `type` and
+       none of the behavioral keys (`$expression`, `$compute`, `$prototype`, `$handler`) — the
+       expanded-signal / typed-def shape `JxStateObject` describes. A literal is replaced by the
+       JSON test value itself, which is a Shape-1 naked entry; `JxStateDefinition` spells that
+       shape as `JxStateObject`, whose typed keys neither a `JsonObject` nor a spread copy can prove
+       statically (the spread drops the index signature its typed keys are checked against). */
+    state[name] = (
+      kind === "signal" ? { ...(current as JxStateObject), default: value } : value
+    ) as JxStateDefinition;
     seeded = true;
   }
   if (!seeded) {
     return renderDoc;
   }
-  return { ...renderDoc, state } as JxMutableNode;
+  return { ...renderDoc, state };
 }

package/src/content/collection-match.ts

@@ -32,12 +32,10 @@
 import { defaultContentFormat, formatByName } from "../format/format-host";
 import { projectState } from "../store";
 import { resolveI18n } from "@jxsuite/schema/locale";
+import { LOCALE_PLACEHOLDER } from "../canvas/asset-resolve";
 import type { ContentSectionEntry } from "../types";
 import type { ProjectConfig } from "@jxsuite/schema/types";
 
-/** The placeholder a localized `source` carries, standing for one directory per declared locale. */
-export const LOCALE_PLACEHOLDER = "{locale}";
-
 /** What a path's collection is, and everything a caller needs in order to act on it. */
 export interface CollectionMatch {
   name: string;
@@ -69,11 +67,14 @@ function normalize(path: string): string {
 
 /** The config a lookup reads: the caller's, or the open project's. */
 function configOf(config: ProjectConfig | null | undefined): ProjectConfig | null {
-  return config ?? (projectState?.projectConfig as ProjectConfig | null | undefined) ?? null;
+  return config ?? projectState?.projectConfig ?? null;
 }
 
 /** The `content` section of a config, or an empty one. */
 function contentSection(config: ProjectConfig | null): Record<string, ContentSectionEntry> {
+  /* SAFETY: `content` is the parser extension's section — collection name → entry object, its
+     project fragment schema the source of truth. `ContentSectionEntry` names only the fields Studio
+     reads, every one optional, and each reader below tests `source` before using it. */
   return (config?.content ?? {}) as Record<string, ContentSectionEntry>;
 }
 

package/src/content/draft-state.ts

@@ -20,6 +20,7 @@
 
 import { reactive } from "../reactivity";
 import type { ContentTypeSchema } from "@jxsuite/schema/types";
+import type { EntryFields } from "./entry-fields";
 
 /** The conventional frontmatter boolean that marks an entry a draft (site-architecture.md §7.6). */
 export const DRAFT_FIELD = "draft";
@@ -44,7 +45,7 @@ export const DRAFT_MEANING =
  * Takes the entry's FIELDS, whichever record they live in — `content/entry-fields.ts` answers that,
  * because a JSON collection's entry has no frontmatter and its `draft` key is on the document.
  */
-export function isDraftEntry(fields: Record<string, unknown> | null | undefined): boolean {
+export function isDraftEntry(fields: EntryFields | null | undefined): boolean {
   return fields?.[DRAFT_FIELD] === true;
 }
 
@@ -63,7 +64,7 @@ export function schemaDeclaresDraft(schema: ContentTypeSchema | null | undefined
  */
 export function hasDraftAxis(
   schema: ContentTypeSchema | null | undefined,
-  fields?: Record<string, unknown> | null,
+  fields?: EntryFields | null,
 ): boolean {
   return schemaDeclaresDraft(schema) || isDraftEntry(fields);
 }
@@ -100,7 +101,7 @@ export function setIncludeDrafts(include: boolean): void {
  */
 export function applyDraftFilter<T>(
   items: readonly T[],
-  fieldsOf: (item: T) => Record<string, unknown> | null | undefined,
+  fieldsOf: (item: T) => EntryFields | null | undefined,
   includeDrafts: boolean,
 ): readonly T[] {
   return includeDrafts ? items : items.filter((item) => !isDraftEntry(fieldsOf(item)));

package/src/content/entry-commands.ts

@@ -33,7 +33,8 @@ import { invalidateReferenceEntries } from "../ui/form-controls";
 import { reloadDraftAwareGrids } from "../grid/sources/content-source";
 import { setIncludeDrafts } from "./draft-state";
 import { collectionOfPath, entryCollection, entryCollections, seedEntry } from "./entry-model";
-import { LOCALE_PLACEHOLDER, collectionForDirectory } from "./collection-match";
+import { collectionForDirectory } from "./collection-match";
+import { LOCALE_PLACEHOLDER } from "../canvas/asset-resolve";
 import { openEntryEditor, setEntryDraft } from "./entry-editor";
 import { errorMessage } from "@jxsuite/schema/parse";
 import type { EntryCollection } from "./entry-model";
@@ -167,7 +168,7 @@ export async function createEntry(
 
 /** The active tab, when it is a content entry — the subject of the document-level verbs. */
 function activeEntryTab(): Tab | null {
-  const tab = activeTab.value as Tab | null;
+  const tab = activeTab.value;
   return tab && collectionOfPath(tab.documentPath) ? tab : null;
 }
 

package/src/content/entry-editor.ts

@@ -50,6 +50,7 @@ import { mountEntryEditorSurface } from "../surfaces/entry-editor";
 import { paneRegion } from "../ui/regions";
 import { activateTab, workspace } from "../workspace/workspace";
 import { commitEntryFields, entryFields, mutateEntryField } from "./entry-fields";
+import type { EntryFields } from "./entry-fields";
 import { DRAFT_FIELD, DRAFT_MEANING, hasDraftAxis, isDraftEntry } from "./draft-state";
 import { collectionOfPath, missingRequired } from "./entry-model";
 import type { EntryCollection } from "./entry-model";
@@ -57,7 +58,7 @@ import type { EntryEditorSurfaceHandle, EntryEditorView } from "../surfaces/entr
 import type { JsonSchema, SchemaFormContext } from "../ui/schema-form";
 import type { Tab } from "../tabs/tab";
 import type { CanvasSurface } from "../canvas/canvas-surface";
-import type { JsonValue } from "../types";
+import type { JsonObject } from "@jxsuite/schema/types";
 
 /** The `canvasMode` the entry form draws under. */
 export const ENTRY_MODE = "entry";
@@ -120,7 +121,7 @@ export function detachEntryPane(paneId: string): void {
  * has explicitly published something should be able to see that they did.
  */
 export function setEntryDraft(tab: Tab, draft: boolean): void {
-  transactDoc(tab, (t) => mutateEntryField(t, DRAFT_FIELD, draft as JsonValue));
+  transactDoc(tab, (t) => mutateEntryField(t, DRAFT_FIELD, draft));
 }
 
 /** What the tab chip's draft pill says. A value, drawn by `surfaces/tab-strip.json`. */
@@ -169,7 +170,7 @@ function formContext(tab: Tab): SchemaFormContext {
     fieldKeyPrefix: `entry:${tab.id}`,
     resolvePointer: (pointer, scope) =>
       resolveContextPointer(pointer, {
-        projectConfig: (projectState?.projectConfig ?? {}) as Record<string, unknown>,
+        projectConfig: projectState?.projectConfig ?? {},
         scope,
       }),
   };
@@ -185,13 +186,14 @@ function formContext(tab: Tab): SchemaFormContext {
  */
 function absentRequiredErrors(
   collection: EntryCollection,
-  fields: Record<string, unknown>,
+  fields: EntryFields,
 ): Record<string, string> {
-  const errors: Record<string, string> = {};
-  for (const field of missingRequired(collection.schema, fields)) {
-    errors[field] = "Required — this entry does not have one.";
-  }
-  return errors;
+  return Object.fromEntries(
+    missingRequired(collection.schema, fields).map((field) => [
+      field,
+      "Required — this entry does not have one.",
+    ]),
+  );
 }
 
 /** What the document says when the file belongs to no collection: the reason, then the fix. */
@@ -280,12 +282,22 @@ export function renderEntryMode(surface: CanvasSurface, tab: Tab): void {
       return;
     }
     const fields = entryFields(tab);
-    const form = mountSchemaForm(`entry:${paneId}`, collection.schema as JsonSchema, fields, {
-      context: formContext(tab),
-      errors: absentRequiredErrors(collection, fields),
-      onChange: (patch) => commitEntryFields(tab, patch),
-      rerender: redraw,
-    });
+    /* SAFETY: `collection` comes from `collectionOfPath`, which matches only a content type that
+       declares a `schema` (`findContentTypeSchema` refuses one without), and that schema is the
+       collection's JSON Schema — the shape `JsonSchema` names for the form. `fields` is a
+       frontmatter block or a JSON entry's own root (entry-fields.ts), both parsed from YAML or
+       JSON text, so every value is JSON; a key an editor cleared reads as absent either way. */
+    const form = mountSchemaForm(
+      `entry:${paneId}`,
+      collection.schema as JsonSchema,
+      fields as JsonObject,
+      {
+        context: formContext(tab),
+        errors: absentRequiredErrors(collection, fields),
+        onChange: (patch) => commitEntryFields(tab, patch),
+        rerender: redraw,
+      },
+    );
     if (form.parentNode !== formHost) {
       formHost.replaceChildren(form);
     }
@@ -332,7 +344,7 @@ export function renderEntryMode(surface: CanvasSurface, tab: Tab): void {
       // Never this effect's guess. `tab.doc.document` is also the reference every transaction
       // Replaces, so it is how an undo reaches the form whichever store the edit was in.
       void tab.doc.document;
-      void tab.doc.content?.frontmatter;
+      void tab.doc.content.frontmatter;
       void projectState?.projectConfig?.content;
       draw();
     });
@@ -365,7 +377,7 @@ export async function openEntryEditor(path: string): Promise<Tab | null> {
     tab.session.ui.canvasMode = ENTRY_MODE;
     tab.session.ui.preview = false;
     activateTab(id);
-    return tab as Tab;
+    return tab;
   }
   return null;
 }

package/src/content/entry-fields.ts

@@ -32,9 +32,16 @@ import { cloneValue } from "@jxsuite/schema/doc-ops";
 import { notePreviewOverlayEdit } from "../preview/preview-overlay";
 import { recordDocOp } from "../tabs/patch-ops";
 import { mutateUpdateFrontmatter, transactDoc } from "../tabs/transact";
+import type { JxDocumentValue } from "@jxsuite/schema/types";
 import type { Tab } from "../tabs/tab";
 import type { JsonValue } from "../types";
 
+/**
+ * An entry's fields, whichever record holds them: a frontmatter block's keys, or a JSON entry's own
+ * document keys. `undefined` is a key an editor has cleared.
+ */
+export type EntryFields = Record<string, JxDocumentValue | undefined>;
+
 /**
  * Whether this tab's entry fields are the document itself rather than a frontmatter block.
  *
@@ -56,10 +63,8 @@ function fieldsAreDocument(tab: Tab): boolean {
  * reactive tab, and a copy would break that. It is also the identity a caller can compare against
  * `tab.doc.document` to see which store answered.
  */
-export function entryFields(tab: Tab): Record<string, unknown> {
-  return fieldsAreDocument(tab)
-    ? (tab.doc.document as unknown as Record<string, unknown>)
-    : (tab.doc.content?.frontmatter ?? {});
+export function entryFields(tab: Tab): EntryFields {
+  return fieldsAreDocument(tab) ? tab.doc.document : tab.doc.content.frontmatter;
 }
 
 /**
@@ -72,7 +77,7 @@ export function entryFields(tab: Tab): Record<string, unknown> {
  * is already the "not surgically patchable, fall back" signal `transactDoc` reads.
  */
 function mutateDocumentField(tab: Tab, field: string, value?: JsonValue): void {
-  const doc = tab.doc.document as unknown as Record<string, unknown>;
+  const doc = tab.doc.document;
   const before = Object.hasOwn(doc, field) ? cloneValue(doc[field]) : undefined;
   const deletes = value === undefined || value === null || value === "";
   if (deletes) {
@@ -113,10 +118,10 @@ export function mutateEntryField(tab: Tab, field: string, value?: JsonValue): vo
  * `renderForm` emits single-key patches today, but committing per key would put a multi-key patch
  * on the undo stack as several steps — and an author who changed one thing expects one ⌘Z.
  */
-export function commitEntryFields(tab: Tab, patch: Record<string, unknown>): void {
+export function commitEntryFields(tab: Tab, patch: Record<string, JsonValue | undefined>): void {
   transactDoc(tab, (t) => {
     for (const [field, value] of Object.entries(patch)) {
-      mutateEntryField(t, field, value as JsonValue);
+      mutateEntryField(t, field, value);
     }
   });
 }