@jxsuite/studio 0.37.1 → 1.1.0

package/src/tabs/tab.ts

@@ -4,14 +4,16 @@ import { formatByName, formatForPath } from "../format/format-host";
 import { normalizeArrayChildren } from "../state";
 import type {
   DocumentStackEntry,
+  FormulaEditDef,
   FunctionEditDef,
   GitBranchesResult,
   GitDiffState,
   GitStatusResult,
   InlineEditDef,
+  JsonValue,
 } from "../types";
 import type { JxMutableNode } from "@jxsuite/schema/types";
-import type { JxDocOp } from "./patch-ops";
+import type { JxDocOp, JxFmOp } from "./patch-ops";
 
 export interface TabUi {
   rightTab: string;
@@ -20,12 +22,26 @@ export interface TabUi {
   preview: boolean;
   /** Show elements inherited from the page's layout (pages with an effective layout only). */
   showLayout: boolean;
+  /** Above-canvas frontmatter Properties accordion expanded (content-collection docs, edit mode). */
+  frontmatterOpen: boolean;
   /** Chosen literal values for dynamic route params (e.g. { sku: "mini-trencher" }). */
   previewParams: Record<string, string>;
+  /**
+   * Chosen test values for a component doc's props (state entries), seeded into the canvas render
+   * so a non-instantiated component previews with real data (M6) — the previewParams mirror.
+   */
+  previewProps: Record<string, JsonValue> | null;
   zoom: number;
+  /**
+   * Edit-mode content zoom — browser-page-zoom semantics (content reflows at the zoomed effective
+   * width while the canvas footprint stays fixed), unlike `zoom` which pan/zooms the whole canvas.
+   */
+  editZoom: number;
   activeMedia: string | null;
   activeSelector: string | null;
   editingFunction: FunctionEditDef | null;
+  /** Full-screen formula workspace target ($expression editing); editingFunction wins if both set. */
+  editingFormula: FormulaEditDef | null;
   featureToggles: Record<string, boolean>;
   styleSections: Record<string, boolean>;
   inspectorSections: Record<string, boolean>;
@@ -46,6 +62,18 @@ export interface TabUi {
   pendingInlineEdit: InlineEditDef | null;
 }
 
+/**
+ * A live (iframe-evaluated) expression preview retained per editing target (M6). Stored on
+ * `session.canvas` beside `scope` — plain wire data (path-key → display-string pairs), rebuilt into
+ * an ExpressionPreview by services/live-preview.ts on read.
+ */
+export interface StoredLivePreview {
+  /** Serialized expression + context the values were computed for (staleness check). */
+  key: string;
+  values: [string, string][];
+  error: string | null;
+}
+
 interface HistorySnapshot {
   /** Full document at this state (checkpoint), or null when the ops describe the transition. */
   document: Record<string, unknown> | null;
@@ -57,6 +85,8 @@ interface HistorySnapshot {
   forwardOps?: JxDocOp[] | null;
   /** Replayable ops transforming this state back into the previous one. */
   inverseOps?: JxDocOp[] | null;
+  /** Frontmatter key changes in this transaction (before/after values, replayed both ways). */
+  fmOps?: JxFmOp[] | null;
 }
 
 export interface Tab {
@@ -89,6 +119,9 @@ export interface Tab {
       // The bridge as a `dataScope` message and read by the data-explorer panel. Plain data now —
       // The old live `EffectScope` (with `.stop()`) moved into the iframe realm with buildScope.
       scope: Record<string, unknown> | null;
+      // Latest live (iframe-evaluated) expression previews keyed by editing-target id, stored
+      // Beside `scope` the same way (services/live-preview.ts owns reads/writes).
+      livePreviews: Record<string, StoredLivePreview> | null;
       error: string | null;
       pendingInlineEdit: InlineEditDef | null;
     };
@@ -109,8 +142,11 @@ function createDefaultUi(canvasMode: string, preview = false) {
     activeMedia: null,
     activeSelector: null,
     canvasMode,
+    editZoom: 1,
+    editingFormula: null,
     editingFunction: null,
     featureToggles: {},
+    frontmatterOpen: true,
     gitBranches: null,
     gitCommitMessage: "",
     gitDiffState: null,
@@ -121,6 +157,7 @@ function createDefaultUi(canvasMode: string, preview = false) {
     pendingInlineEdit: null,
     preview,
     previewParams: {},
+    previewProps: null,
     rightTab: "properties",
     settingsTab: "stylebook",
     showLayout: true,
@@ -204,6 +241,7 @@ export function createTab({
     session: reactive({
       canvas: {
         error: null,
+        livePreviews: null,
         pendingInlineEdit: null,
         scope: null,
         status: "idle",

package/src/tabs/transact.ts

@@ -8,16 +8,23 @@ import {
   endRecording,
   getPatchConsumer,
   recordDocOp,
+  recordFmOp,
   recordPatch,
 } from "./patch-ops";
 
-import type { JxDocOp, JxDocOpPair, TransactionRecord } from "./patch-ops";
+import type { JxDocOp, JxDocOpPair, JxFmOp, TransactionRecord } from "./patch-ops";
 
 import type { Tab } from "../tabs/tab";
 import type { JxPath } from "../state";
 
 import type { JsonValue } from "../types";
-import type { JxEventBinding, JxMutableNode, JxStateObject, JxStyle } from "@jxsuite/schema/types";
+import type {
+  JxAttributeValue,
+  JxEventBinding,
+  JxMutableNode,
+  JxStateObject,
+  JxStyle,
+} from "@jxsuite/schema/types";
 import { ensureNestedStyle, getNestedStyle, isEventBinding } from "@jxsuite/schema/guards";
 
 const HISTORY_LIMIT = 100;
@@ -205,10 +212,14 @@ function pushHistoryEntry(
   selectionBefore: JxPath | null,
 ) {
   const truncated = tab.history.snapshots.slice(0, tab.history.index + 1);
-  const useOps = patchHistoryEnabled() && record.invertible && record.docOps.length > 0;
+  const useOps =
+    patchHistoryEnabled() &&
+    record.invertible &&
+    (record.docOps.length > 0 || record.fmOps.length > 0);
   const needCheckpoint = !useOps || truncated.length % CHECKPOINT_INTERVAL === 0;
   truncated.push({
     document: needCheckpoint ? jsonClone(raw) : null,
+    fmOps: useOps && record.fmOps.length > 0 ? record.fmOps : null,
     forwardOps: useOps ? record.docOps.map((p) => p.forward) : null,
     inverseOps: useOps ? record.docOps.map((p) => p.inverse) : null,
     selection: tab.session.selection ? [...tab.session.selection] : null,
@@ -343,7 +354,7 @@ function applyDocOp(tab: Tab, op: JxDocOp) {
         toIndex: op.toIndex,
         toParentPath: op.toParentPath,
       });
-      return;
+      break;
     }
     default: {
       break;
@@ -471,14 +482,23 @@ export function undo(tab: Tab) {
   }
   const entry = tab.history.snapshots[tab.history.index]!;
   const inverseOps = patchHistoryEnabled() ? entry.inverseOps : null;
-  if (inverseOps && inverseOps.length > 0) {
+  const fmOps = patchHistoryEnabled() ? entry.fmOps : null;
+  if ((inverseOps && inverseOps.length > 0) || (fmOps && fmOps.length > 0)) {
     // Surgical path: apply inverse ops through the normal transaction pipeline (the canvas
     // Patches in place when it can), in reverse recording order.
     transactDoc(
       tab,
       (t) => {
-        for (let i = inverseOps.length - 1; i >= 0; i--) {
-          applyDocOp(t, toRaw(inverseOps[i]) as JxDocOp);
+        if (inverseOps) {
+          for (let i = inverseOps.length - 1; i >= 0; i--) {
+            applyDocOp(t, toRaw(inverseOps[i]) as JxDocOp);
+          }
+        }
+        if (fmOps) {
+          for (let i = fmOps.length - 1; i >= 0; i--) {
+            const op = toRaw(fmOps[i]) as JxFmOp;
+            applyFmState(t, op.field, op.before);
+          }
         }
       },
       { origin: "history", skipHistory: true },
@@ -505,12 +525,21 @@ export function redo(tab: Tab) {
   }
   const entry = tab.history.snapshots[tab.history.index + 1]!;
   const forwardOps = patchHistoryEnabled() ? entry.forwardOps : null;
-  if (forwardOps && forwardOps.length > 0) {
+  const fmOps = patchHistoryEnabled() ? entry.fmOps : null;
+  if ((forwardOps && forwardOps.length > 0) || (fmOps && fmOps.length > 0)) {
     transactDoc(
       tab,
       (t) => {
-        for (const op of forwardOps) {
-          applyDocOp(t, toRaw(op) as JxDocOp);
+        if (forwardOps) {
+          for (const op of forwardOps) {
+            applyDocOp(t, toRaw(op) as JxDocOp);
+          }
+        }
+        if (fmOps) {
+          for (const op of fmOps) {
+            const raw = toRaw(op) as JxFmOp;
+            applyFmState(t, raw.field, raw.after);
+          }
         }
       },
       { origin: "history", skipHistory: true },
@@ -746,13 +775,13 @@ export function mutateUpdateStyle(tab: Tab, path: JxPath, prop: string, value: s
  * @param {Tab} tab
  * @param {JxPath} path
  * @param {string} attr
- * @param {string | undefined} value
+ * @param {JxAttributeValue | undefined} value — a literal, `$ref` binding, or `${}` template.
  */
 export function mutateUpdateAttribute(
   tab: Tab,
   path: JxPath,
   attr: string,
-  value?: string | undefined,
+  value?: JxAttributeValue | undefined,
 ) {
   const node = getNodeAtPath(tab.doc.document, path);
   const attrsBefore = cloneValue(node.attributes);
@@ -1196,10 +1225,28 @@ export function mutateRenameSwitchCase(tab: Tab, path: JxPath, oldName: string,
  * @param {JsonValue} value
  */
 export function mutateUpdateFrontmatter(tab: Tab, field: string, value?: JsonValue) {
-  if (value === undefined || value === null || value === "") {
+  const fm = tab.doc.content.frontmatter;
+  const before = Object.hasOwn(fm, field) ? cloneValue(fm[field]) : undefined;
+  const deletes = value === undefined || value === null || value === "";
+  if (deletes) {
+    delete fm[field];
+  } else {
+    fm[field] = value;
+  }
+  const after = deletes ? undefined : cloneValue(value);
+  recordFmOp({ after, before, field });
+  tab.doc.dirty = true;
+}
+
+/**
+ * Restore a frontmatter key to a recorded history state: `undefined` means the key was absent.
+ * Unlike `mutateUpdateFrontmatter`, values like `""`/`false`/`null` are written verbatim (source
+ * round-trips can put them there) and no fm op is recorded — history replay must not re-record.
+ */
+function applyFmState(tab: Tab, field: string, value: unknown) {
+  if (value === undefined) {
     delete tab.doc.content.frontmatter[field];
   } else {
     tab.doc.content.frontmatter[field] = value;
   }
-  tab.doc.dirty = true;
 }

package/src/types.ts

@@ -1,6 +1,11 @@
 /// <reference lib="dom" />
 import type { CollabHandle } from "@jxsuite/collab/provider";
-import type { JxMutableNode, JxPath, ProjectConfig } from "@jxsuite/schema/types";
+import type {
+  ContentTypeSchema,
+  JxMutableNode,
+  JxPath,
+  ProjectConfig,
+} from "@jxsuite/schema/types";
 
 // ─── Wire types (the Studio Backend Protocol) ───────────────────────────────
 /* The request/response shapes every backend serves live in @jxsuite/protocol;
@@ -11,7 +16,16 @@ import type {
   CfConnection,
   CodeServiceResult,
   ComponentMeta,
+  DataConnectionsResponse,
+  DataConnectionTestResult,
+  DataPushResult,
+  DataRowDelete,
+  DataRowInsert,
+  DataRowsQuery,
+  DataRowsResult,
+  DataRowUpdate,
   DirEntry,
+  ExtensionsInfo,
   FsEvent,
   GitBranchesResult,
   GitLogEntry,
@@ -22,8 +36,11 @@ import type {
   PackageInfo,
   PackageOpResult,
   ProjectListEntry,
+  ProjectSchemasResponse,
   RecentProjectEntry,
   RenameResult,
+  SecretsSetRequest,
+  SecretsSetResponse,
   StarterInfo,
 } from "@jxsuite/protocol";
 
@@ -35,8 +52,24 @@ export type {
   CodeServiceResult,
   ComponentMeta,
   ComponentSlotMeta,
+  DataColumnMeta,
+  DataConnectionInfo,
+  DataConnectionsResponse,
+  DataConnectionTestResult,
+  DataConnectorInfo,
+  DataPushRequest,
+  DataPushResult,
+  DataPushStep,
+  DataRowDelete,
+  DataRowInsert,
+  DataRowsQuery,
+  DataRowsResult,
+  DataRowUpdate,
   DirEntry,
   ErrorBody,
+  ExtensionContributionInfo,
+  ExtensionProjectBlock,
+  ExtensionsInfo,
   FsEvent,
   GitBranchesResult,
   GitFileStatus,
@@ -49,12 +82,36 @@ export type {
   PackageInfo,
   PackageOpResult,
   ProjectListEntry,
+  ProjectSchemasResponse,
   PullRequestInfo,
   RecentProjectEntry,
   RenameResult,
+  SecretsListResponse,
+  SecretsSetRequest,
+  SecretsSetResponse,
   StarterInfo,
 } from "@jxsuite/protocol";
 
+/** Repository-access onboarding state returned by `StudioPlatform.getAccountStatus`. */
+export interface AccountStatus {
+  /** GitHub App installations (personal + organization) visible to the signed-in user. */
+  installations: { id: number; account: string | null }[];
+  /** Where to install the App (github.com/apps/<slug>/installations/new), when known. */
+  appInstallUrl?: string;
+}
+
+/** A repository visible to `StudioPlatform.listRepos` (the add-existing-repository picker). */
+export interface RepoInfo {
+  owner: string;
+  name: string;
+  fullName: string;
+  private: boolean;
+  defaultBranch: string;
+  permission: "admin" | "write" | "read" | "none";
+  /** Already recognized as a Jx project (topic-tagged / cataloged). */
+  isJxProject: boolean;
+}
+
 export interface StudioPlatform {
   id: string;
   projectRoot: string;
@@ -126,8 +183,39 @@ export interface StudioPlatform {
   searchFiles: (query: string, extensions?: string[]) => Promise<DirEntry[]>;
   /** List the project's registered format classes (auto-discovered from imports). */
   listFormats?: () => Promise<unknown[]>;
+  /**
+   * List the project's enabled extension packages with their project-section contributions
+   * (specs/extensions.md §9/§9.1) — the formats route's sibling `extensions` payload. Optional:
+   * platforms without it lose descriptor-contributed settings sections.
+   */
+  listExtensions?: () => Promise<ExtensionsInfo[]>;
+  /**
+   * Fetch the project's generated entry schemas (project.schema.json / document.schema.json),
+   * PRE-BUNDLED into self-contained documents for editor registration. Optional: without it the
+   * JSON editor keeps the bundled core schemas.
+   */
+  fetchProjectSchemas?: () => Promise<ProjectSchemasResponse>;
   /** Invoke a format capability (parse/serialize) — { format, action, source?, doc?, options? }. */
   formatAction?: (payload: Record<string, unknown>) => Promise<unknown>;
+  // ─── Data surface + secrets (owner console; specs/extensions.md §13) ────────
+  // Optional as a family: backends without the connector data routes omit them all, and Studio
+  // Hides the data grid and connection/push/test actions. Row CRUD is the ADMIN path — it
+  // Intentionally bypasses table permission rules; the backend boundary is the gate.
+  /** List connector connections with configured state, table names, and provider metadata. */
+  dataConnections?: () => Promise<DataConnectionsResponse>;
+  /** Probe one connection through the backend's connector registry. */
+  dataConnectionTest?: (connection: string) => Promise<DataConnectionTestResult>;
+  /** Additive schema push; `dryRun` compiles the plan without applying it. */
+  dataPush?: (opts?: { connection?: string; dryRun?: boolean }) => Promise<DataPushResult>;
+  /** Page a table's rows with introspected column metadata. */
+  dataRows?: (query: DataRowsQuery) => Promise<DataRowsResult>;
+  dataInsertRow?: (req: DataRowInsert) => Promise<{ row: Record<string, unknown> }>;
+  dataUpdateRow?: (req: DataRowUpdate) => Promise<{ row: Record<string, unknown> }>;
+  dataDeleteRow?: (req: DataRowDelete) => Promise<{ ok: boolean }>;
+  /** Configured secret env-var NAMES — never values. */
+  listSecrets?: () => Promise<string[]>;
+  /** Write/remove secrets in the backend store (.dev.vars locally); names-only response. */
+  setSecrets?: (req: SecretsSetRequest) => Promise<SecretsSetResponse>;
   fetchPluginSchema: (src: string, prototype?: string, base?: string) => Promise<unknown>;
   /**
    * Resolve a class-prototype config through the backend's `/__jx_resolve__` pipeline (with the
@@ -235,6 +323,25 @@ export interface StudioPlatform {
   // ─── Identity & hosting connections (publish surface) ───────────────────────
   /** The signed-in user's identity, when the platform has one (cloud). */
   getUser?: () => Promise<{ login: string; name?: string; avatarUrl?: string } | null>;
+  /**
+   * Repository-access onboarding state: the platform's GitHub App installations visible to this
+   * user and where to install the App. Cloud-only; when the list is empty Studio's welcome screen
+   * prompts the user to install the App (without it, no repos are reachable). Null = unknown (don't
+   * prompt).
+   */
+  getAccountStatus?: () => Promise<AccountStatus | null>;
+  /**
+   * Browse every repository the platform's account link can reach — personal and organization repos
+   * covered by a GitHub App installation on cloud. Backs the "Add Existing Repository" picker;
+   * local platforms omit it (the OS picker / clone flow covers them).
+   */
+  listRepos?: () => Promise<RepoInfo[]>;
+  /**
+   * Adopt an existing repository as a Jx project and return its catalogue root key (openable via
+   * the recent-projects path). Rejects with a structured message when the repository carries no
+   * project.json.
+   */
+  importProject?: (opts: { owner: string; name: string }) => Promise<{ root: string }>;
   /**
    * Open a pull request for the current branch. Cloud platforms implement it against their session;
    * local platforms omit it and Studio falls back to a direct GitHub API call with the user's
@@ -273,6 +380,18 @@ export interface StudioPlatform {
 
 // ─── Studio Types ───────────────────────────────────────────────────────────
 
+/**
+ * A project.json `content` section entry, as the studio consumes it. The parser extension owns the
+ * full shape (its project fragment schema is the validation source of truth); the studio only reads
+ * these fields.
+ */
+export interface ContentSectionEntry {
+  source?: string;
+  format?: string;
+  schema?: ContentTypeSchema;
+  $elements?: unknown[];
+}
+
 export interface CanvasPanel {
   mediaName: string;
   element: HTMLElement;
@@ -308,6 +427,18 @@ export interface FunctionEditDef {
   parameters?: string[];
 }
 
+/**
+ * Identifies which document position's `$expression` the full-screen formula workspace is editing:
+ * a state entry (`type: "def"` + defName) or an element event binding (`type: "event"` + path +
+ * eventKey). Mirrors FunctionEditDef, the Monaco function editor's target shape.
+ */
+export interface FormulaEditDef {
+  type: "def" | "event";
+  defName?: string;
+  path?: JxPath;
+  eventKey?: string;
+}
+
 export interface GitDiffState {
   filePath: string;
   originalContent: string;