@jxsuite/studio 1.1.0 → 1.3.0

package/src/platforms/cloud.ts

@@ -334,7 +334,9 @@ export function createCloudPlatform(project: CloudProject | null): StudioPlatfor
      * {kind:"git"} notices this handler ignores.
      */
     subscribeFileEvents(handler: (events: FsEvent[]) => void) {
-      if (typeof WebSocket === "undefined" || typeof location === "undefined") {
+      // No project means an empty base, so the bare `/events` URL hits no gateway route.
+      // That fails in a reconnect loop; mirror `collab`'s guard and degrade to no-op on the hub.
+      if (!project || typeof WebSocket === "undefined" || typeof location === "undefined") {
         return () => {};
       }
       let socket: WebSocket | null = null;

package/src/project-list.ts

@@ -36,3 +36,8 @@ export function getProjectList(): ProjectListEntry[] {
 export function resetProjectList(): void {
   cache = [];
 }
+
+/** Seed seam for tests and the screenshot automation hook (staged catalogues). */
+export function seedProjectList(entries: ProjectListEntry[]): void {
+  cache = entries;
+}

package/src/publish/publish-panel.ts

@@ -339,6 +339,23 @@ function render(): void {
   }
 }
 
+/**
+ * Automation-only seam (scripts/screenshots): open the modal directly in its connected state with a
+ * canned deployment, bypassing {@link loadConnection} so no Cloudflare request ever fires. The
+ * active project's `build.deploy` block still supplies the connected project/URL line.
+ */
+export function seedPublishConnected(options: {
+  accountId?: string;
+  deployment: PagesDeploymentInfo;
+}): void {
+  _connection = { accountId: options.accountId ?? "demo-account", connected: true };
+  _accounts = [];
+  _deployment = options.deployment;
+  _error = "";
+  _busy = false;
+  render();
+}
+
 /** Open the publish modal for the active project. */
 export function openPublishPanel(): void {
   const config = currentConfig();

package/src/services/automation.ts

@@ -10,18 +10,30 @@
  */
 
 import { renderOnly, updateUi } from "../store";
-import { activeTab, workspace } from "../workspace/workspace";
+import { setProjectState } from "../state";
+import { seedProjectList } from "../project-list";
+import { activeTab, closeAllTabs, workspace } from "../workspace/workspace";
+import type { ProjectListEntry } from "../types";
 import { applyPanelCollapse, view } from "../view";
 import { setEditZoom as applyEditZoomLevel } from "../canvas/canvas-utils";
+import { collabState } from "../collab/collab-state";
+import type { PeerPresence } from "../collab/collab-state";
+import type { SeededAssistantMessage } from "../panels/ai-panel";
+import type { PagesDeploymentInfo } from "../publish/pages-service";
 import type { JxPath } from "../state";
 
 /** Callbacks injected from studio.ts (module-local helpers or imports kept out of this module). */
 export interface AutomationDeps {
   getCanvasMode: () => string;
   openBrowseModal: () => void;
+  openConnectorGrid: (connection: string | undefined, table: string) => void;
   openNewProjectModal: () => void;
+  openQuickSearchPalette: () => void;
+  openSettingsModal: (section?: string) => void;
   render: () => void;
   renderActivityBar: () => void;
+  seedAssistantMessages: (messages: SeededAssistantMessage[]) => void;
+  seedPublishConnected: (options: { accountId?: string; deployment: PagesDeploymentInfo }) => void;
   setCanvasMode: (mode: string) => void;
   statusMessage: (text: string) => void;
 }
@@ -30,7 +42,14 @@ export interface AutomationApi {
   editDef: (defName: string) => void;
   editFunction: (path: JxPath, eventKey: string) => void;
   openBrowse: () => void;
+  openDataGrid: (options: { connection?: string; table: string }) => void;
   openNewProject: () => void;
+  openQuickSearch: () => void;
+  openSettings: (section?: string) => void;
+  seedAssistant: (options: { messages: SeededAssistantMessage[] }) => void;
+  seedCollab: (options: { peers: PeerPresence[] }) => void;
+  seedPublish: (options: { accountId?: string; deployment: PagesDeploymentInfo }) => void;
+  showWelcome: (options?: { projects?: ProjectListEntry[] }) => void;
   getState: () => {
     activeTabId: string | null;
     canvasMode: string;
@@ -66,9 +85,56 @@ export function createAutomationApi(deps: AutomationDeps): AutomationApi {
     openBrowse() {
       deps.openBrowseModal();
     },
+    openDataGrid(options: { connection?: string; table: string }) {
+      deps.openConnectorGrid(options.connection, options.table);
+    },
     openNewProject() {
       deps.openNewProjectModal();
     },
+    openQuickSearch() {
+      deps.openQuickSearchPalette();
+    },
+    openSettings(section?: string) {
+      deps.openSettingsModal(section);
+    },
+    seedAssistant(options: { messages: SeededAssistantMessage[] }) {
+      deps.seedAssistantMessages(options.messages);
+    },
+    seedCollab(options: { peers: PeerPresence[] }) {
+      // Stage a live co-editing session on the active tab: the toolbar's presence chips and the
+      // Canvas peer-selection boxes both read this same reactive store.
+      const tab = activeTab.value;
+      if (!tab) {
+        return;
+      }
+      const state = collabState(tab);
+      state.status = "synced";
+      state.active = true;
+      state.peers = options.peers.map((peer) => ({
+        ...peer,
+        state: {
+          ...peer.state,
+          focusedPath: peer.state.focusedPath ?? tab.documentPath,
+        },
+      }));
+      deps.render();
+    },
+    seedPublish(options: { accountId?: string; deployment: PagesDeploymentInfo }) {
+      deps.seedPublishConnected(options);
+    },
+    showWelcome(options?: { projects?: ProjectListEntry[] }) {
+      // The devserver platform auto-opens the repo-root project on boot; the welcome
+      // Screen only renders with no project and no tabs, so stage that state directly.
+      // A staged catalogue replaces the real one (screenshots must not leak local paths).
+      closeAllTabs();
+      setProjectState(null);
+      if (options?.projects) {
+        seedProjectList(options.projects);
+      }
+      view.chatPanelCollapsed = true;
+      applyPanelCollapse();
+      deps.render();
+    },
     getState() {
       return {
         activeTabId: workspace.activeTabId,

package/src/settings/css-vars-editor.ts

@@ -1,17 +1,26 @@
 /// <reference lib="dom" />
 /**
- * CSS Variables editor — form-based editor for managing design tokens. Colors and fonts are NOT
- * media-aware; sizes/spacing are media-aware.
+ * CSS Variables editor — form-based editor for managing design tokens. Colors are scheme-aware
+ * (per-scheme overrides in `@--dark`-style blocks, spec §9.5); sizes/spacing are media-aware; fonts
+ * are neither.
  */
 
 import { html, render as litRender, nothing } from "lit-html";
 import { ref } from "lit-html/directives/ref.js";
 import { projectState } from "../store";
 import { getEffectiveMedia, updateSiteConfig } from "../site-context";
+import { postSiteStyleToLiveHosts } from "../canvas/iframe-host";
+import { isSchemeQuery, schemeOfQuery } from "../utils/canvas-media";
 import { friendlyNameToVar, varDisplayName } from "../utils/studio-utils";
 
 import type { JxStyle } from "@jxsuite/schema/types";
 
+/** A declared scheme query in $media: the block key name plus the scheme it targets. */
+export interface SchemeEntry {
+  name: string;
+  scheme: "light" | "dark";
+}
+
 /** @param {HTMLElement} container */
 export function renderCssVarsEditor(container: HTMLElement) {
   const config = projectState?.projectConfig || {};
@@ -50,10 +59,20 @@ export function renderCssVarsEditor(container: HTMLElement) {
     }
   }
 
-  const mediaNames = media ? Object.keys(media).filter((m) => m !== "--") : [];
+  const mediaNames = media
+    ? Object.keys(media).filter((m) => m !== "--" && !isSchemeQuery(String(media[m])))
+    : [];
+  const schemeEntries: SchemeEntry[] = media
+    ? Object.entries(media).flatMap(([name, query]) => {
+        const scheme = schemeOfQuery(String(query));
+        return scheme ? [{ name, scheme }] : [];
+      })
+    : [];
 
   const save = () => {
     void updateSiteConfig({ style: { ...rootStyle } });
+    // Live canvas feedback: replace the site-style sheet in place — no re-render needed.
+    postSiteStyleToLiveHosts();
   };
 
   const updateVar = (name: string, val: string) => {
@@ -61,6 +80,35 @@ export function renderCssVarsEditor(container: HTMLElement) {
     save();
   };
 
+  // Write/clear a per-scheme token override in the scheme's `@--name` block (spec §9.5). An empty
+  // Value clears the override (and drops the block when it empties) — the token inherits the base.
+  const updateSchemeVar = (schemeName: string, varName: string, val: string) => {
+    const key = `@${schemeName}`;
+    if (val) {
+      const block = (rootStyle[key] ??= {}) as Record<string, unknown>;
+      block[varName] = val;
+    } else {
+      const block = rootStyle[key];
+      if (block && typeof block === "object") {
+        delete (block as Record<string, unknown>)[varName];
+        if (Object.keys(block).length === 0) {
+          delete rootStyle[key];
+        }
+      }
+    }
+    save();
+    renderCssVarsEditor(container);
+  };
+
+  // Without a declared scheme query nothing ever shows the scheme UI (here or in the tab bar) —
+  // This is the opt-in affordance for existing projects. Re-render after the async config update
+  // Lands (unlike style edits, $media is not mutated in place).
+  const enableDarkScheme = () => {
+    void updateSiteConfig({
+      $media: { ...config.$media, "--dark": "(prefers-color-scheme: dark)" },
+    }).then(() => renderCssVarsEditor(container));
+  };
+
   const deleteVar = (name: string) => {
     delete rootStyle[name];
     save();
@@ -81,7 +129,16 @@ export function renderCssVarsEditor(container: HTMLElement) {
     <div class="settings-section">
       <h3 class="settings-section-title">CSS Variables</h3>
 
-      ${renderColorSection(groups.color, updateVar, deleteVar, addVar)}
+      ${renderColorSection(
+        groups.color,
+        updateVar,
+        deleteVar,
+        addVar,
+        rootStyle,
+        schemeEntries,
+        updateSchemeVar,
+        enableDarkScheme,
+      )}
       ${renderFontSection(groups.font, updateVar, deleteVar, addVar)}
       ${renderSizeSection(groups.size, updateVar, deleteVar, addVar, rootStyle, mediaNames)}
       ${groups.other.length > 0
@@ -104,6 +161,10 @@ function renderColorSection(
   updateVar: (name: string, val: string) => void,
   deleteVar: (name: string) => void,
   addVar: (prefix: string, friendlyName: string, val: string) => void,
+  rootStyle: JxStyle,
+  schemeEntries: SchemeEntry[],
+  updateSchemeVar: (schemeName: string, varName: string, val: string) => void,
+  enableDarkScheme: () => void,
 ) {
   return html`
     <div class="css-vars-group">
@@ -129,9 +190,66 @@ function renderColorSection(
               <sp-icon-delete slot="icon"></sp-icon-delete>
             </sp-action-button>
           </div>
+          ${schemeEntries.map((entry) =>
+            renderSchemeOverride(name, rootStyle, entry, updateSchemeVar),
+          )}
         `,
       )}
       ${renderAddRow("--color-", "Primary Blue", "#3b82f6", addVar)}
+      ${schemeEntries.length === 0
+        ? html`
+            <sp-action-button
+              size="s"
+              class="css-vars-enable-dark"
+              title="Add a dark color scheme: declares --dark in $media so every color token can carry a dark value"
+              @click=${enableDarkScheme}
+            >
+              Enable dark scheme
+            </sp-action-button>
+          `
+        : nothing}
+    </div>
+  `;
+}
+
+/**
+ * One per-scheme override row under a color token: swatch + field bound to the scheme block's
+ * value. Empty shows "inherits" (the base value applies); clearing deletes the override.
+ *
+ * @param {string} varName
+ * @param {JxStyle} rootStyle
+ * @param {SchemeEntry} entry
+ * @param {(schemeName: string, varName: string, val: string) => void} updateSchemeVar
+ */
+function renderSchemeOverride(
+  varName: string,
+  rootStyle: JxStyle,
+  entry: SchemeEntry,
+  updateSchemeVar: (schemeName: string, varName: string, val: string) => void,
+) {
+  const block = rootStyle[`@${entry.name}`];
+  const current =
+    block && typeof block === "object" ? (block as Record<string, unknown>)[varName] : undefined;
+  const label = entry.scheme === "dark" ? "Dark" : "Light";
+  return html`
+    <div class="css-var-media-row css-var-scheme-row">
+      <span class="css-var-media-label">${label}</span>
+      <div class="css-var-swatch" style="background:${current ?? "transparent"}">
+        <input
+          type="color"
+          .value=${current && String(current).startsWith("#") ? String(current) : "#111111"}
+          @input=${(e: Event) =>
+            updateSchemeVar(entry.name, varName, (e.target as HTMLInputElement).value)}
+        />
+      </div>
+      <sp-textfield
+        size="s"
+        placeholder="inherits"
+        .value=${current == null ? "" : String(current)}
+        @change=${(e: Event) =>
+          updateSchemeVar(entry.name, varName, (e.target as HTMLInputElement).value)}
+        style="flex:1;max-width:160px"
+      ></sp-textfield>
     </div>
   `;
 }

package/src/settings/settings-modal.ts

@@ -106,11 +106,11 @@ let _activeSection = "general";
 
 let _contentEl: HTMLElement | null = null;
 
-export function openSettingsModal() {
+export function openSettingsModal(section?: string) {
   if (_handle) {
     return;
   }
-  _activeSection = "general";
+  _activeSection = section ?? "general";
   renderModal();
   // Refresh descriptor-contributed sections (cached payloads make this cheap) and rerender the
   // Nav once they land. Lazy import breaks the settings-modal ↔ extension-sections module cycle.

package/src/studio.ts

@@ -48,6 +48,7 @@ import { consumePatchedDocument, initCanvasPatcher } from "./canvas/canvas-patch
 import {
   commitActiveEditSession,
   getEditSnapshot,
+  postColorSchemeToLiveHosts,
   setCanvasContextMenuHandler,
   setCanvasSlashHandler,
   setIframePatchEscalation,
@@ -95,6 +96,9 @@ import { renderHeadTemplate } from "./panels/head-panel";
 import { exportCemManifest as _exportCemManifest } from "./services/cem-export";
 import { installAutomationHook } from "./services/automation";
 import { openBrowseModal } from "./browse/browse-modal";
+import { seedAssistantMessages } from "./panels/ai-panel";
+import { seedPublishConnected } from "./publish/publish-panel";
+import { openConnectorGrid } from "./grid/grid-open";
 
 import { getPlatform, hasPlatform, registerPlatform } from "./platform";
 import { parseMediaEntries } from "./utils/canvas-media";
@@ -144,7 +148,8 @@ import {
   renderBlockActionBar,
 } from "./panels/block-action-bar";
 import { initCssData } from "./panels/style-utils";
-import { initQuickSearch } from "./panels/quick-search";
+import { initQuickSearch, openQuickSearch } from "./panels/quick-search";
+import { openSettingsModal } from "./settings/settings-modal";
 import { hydrateAccountStatus } from "./account-status";
 import { hydrateProjectList } from "./project-list";
 import { addRecentProject, hydrateRecentProjects, removeRecentProject } from "./recent-projects";
@@ -390,9 +395,14 @@ if (!hasPlatform()) {
 installAutomationHook({
   getCanvasMode,
   openBrowseModal,
+  openConnectorGrid,
   openNewProjectModal,
+  openQuickSearchPalette: openQuickSearch,
+  openSettingsModal,
   render,
   renderActivityBar,
+  seedAssistantMessages,
+  seedPublishConnected,
   setCanvasMode,
   statusMessage,
 });
@@ -581,6 +591,12 @@ effect(() => {
   }
   scheduleCanvasRender();
 });
+// Color-scheme preview is a document-level attribute flip inside the iframe — deliberately its
+// Own effect, never part of the ui-effect above: flipping the scheme must not re-render.
+effect(() => {
+  const s = activeTab.value?.session.ui.previewColorScheme;
+  postColorSchemeToLiveHosts(s === "light" || s === "dark" ? s : null);
+});
 
 rightPanelMod.mount({
   getCanvasMode,

package/src/tabs/tab.ts

@@ -43,6 +43,12 @@ export interface TabUi {
   /** Full-screen formula workspace target ($expression editing); editingFunction wins if both set. */
   editingFormula: FormulaEditDef | null;
   featureToggles: Record<string, boolean>;
+  /**
+   * Canvas color-scheme preview: follow the OS ("auto") or force a scheme. Drives the
+   * data-color-scheme attribute on the canvas iframe root (spec §9.5) and, in the style sidebar,
+   * which scheme layer edits target.
+   */
+  previewColorScheme: "auto" | "light" | "dark";
   styleSections: Record<string, boolean>;
   inspectorSections: Record<string, boolean>;
   styleShorthands: Record<string, boolean>;
@@ -156,6 +162,7 @@ function createDefaultUi(canvasMode: string, preview = false) {
     inspectorSections: {},
     pendingInlineEdit: null,
     preview,
+    previewColorScheme: "auto" as const,
     previewParams: {},
     previewProps: null,
     rightTab: "properties",

package/src/ui/formula-catalog.ts

@@ -293,7 +293,10 @@ const OPERATOR_META: Record<string, OperatorMeta> = {
 export function operatorEntries(): FormulaCatalogEntry[] {
   const out: FormulaCatalogEntry[] = [];
   for (const op of BLESSED_OPERATORS) {
-    const meta = OPERATOR_META[op];
+    // Own-property lookup only: a bare index would resolve inherited Object.prototype members for
+    // Ops like "toLocaleString", yielding a bogus meta whose undefined group/description breaks
+    // The palette's substring filter.
+    const meta = Object.hasOwn(OPERATOR_META, op) ? OPERATOR_META[op] : undefined;
     if (meta) {
       out.push({
         description: meta.description,

package/src/utils/canvas-media.ts

@@ -2,6 +2,29 @@
 /// <reference lib="dom.iterable" />
 /** Canvas media/breakpoint utilities — pure functions extracted for testability. */
 
+import { pureSchemeOf } from "@jxsuite/runtime";
+
+/**
+ * True when a feature query participates in the forced-scheme contract (spec §9.5) — a pure
+ * prefers-color-scheme query. These surface as the Auto/Light/Dark control, not generic toggles.
+ *
+ * @param {string} query
+ * @returns {boolean}
+ */
+export function isSchemeQuery(query: string): boolean {
+  return pureSchemeOf(query) !== null;
+}
+
+/**
+ * The scheme a feature query targets ("light" | "dark"), or null for non-scheme queries.
+ *
+ * @param {string} query
+ * @returns {"light" | "dark" | null}
+ */
+export function schemeOfQuery(query: string): "light" | "dark" | null {
+  return pureSchemeOf(query);
+}
+
 /**
  * Classify $media entries into size breakpoints (get a canvas each) and feature queries (rendered
  * as toolbar toggles).