@jxsuite/studio 0.0.1

package/src/panels/statusbar.js

@@ -0,0 +1,56 @@
+/** Statusbar — status message display for Jx Studio */
+
+import { statusbarEl, getNodeAtPath, nodeLabel } from "../store.js";
+
+// ─── Module state ────────────────────────────────────────────────────────────
+
+let statusMsg = "";
+/** @type {any} */
+let statusTimeout;
+/** @type {(() => void) | null} */
+let _rerender = null;
+
+/**
+ * Register the callback used to re-render the statusbar. Called once from studio.js during init.
+ *
+ * @param {() => void} fn
+ */
+export function setStatusbarRenderer(fn) {
+  _rerender = fn;
+}
+
+// ─── Statusbar ───────────────────────────────────────────────────────────────
+
+/**
+ * Render the statusbar text. Receives current studio state so the module stays decoupled from the
+ * mutable `S` local in studio.js.
+ *
+ * @param {any} S - Current studio state
+ */
+export function renderStatusbar(S) {
+  const parts = [];
+  if (S.mode === "content") parts.push("Content Mode");
+  if (S.selection) {
+    const node = getNodeAtPath(S.document, S.selection);
+    parts.push(`Selected: ${nodeLabel(node)}`);
+    parts.push(`Path: ${S.selection.join(" > ") || "root"}`);
+  }
+  if (statusMsg) parts.push(statusMsg);
+  statusbarEl.textContent = parts.join("  |  ") || "Jx Studio";
+}
+
+/**
+ * Show a temporary status message.
+ *
+ * @param {any} msg
+ * @param {number} [duration]
+ */
+export function statusMessage(msg, duration = 3000) {
+  statusMsg = msg;
+  _rerender?.();
+  clearTimeout(statusTimeout);
+  statusTimeout = setTimeout(() => {
+    statusMsg = "";
+    _rerender?.();
+  }, duration);
+}

package/src/platform.js

@@ -0,0 +1,31 @@
+/**
+ * Platform.js — Platform Abstraction Layer (PAL)
+ *
+ * Studio is backend-agnostic. Each deployment target (desktop, dev server, cloud) registers a
+ * platform adapter at startup. All file I/O, project loading, and component discovery goes through
+ * this interface.
+ *
+ * See spec/desktop.md §3 for the full StudioPlatform interface.
+ */
+
+/** @typedef {Record<string, any>} StudioPlatform */
+
+/** @type {StudioPlatform | null} */
+let _platform = null;
+
+/** @param {StudioPlatform} platform */
+export function registerPlatform(platform) {
+  _platform = platform;
+}
+
+/** @returns {StudioPlatform} */
+export function getPlatform() {
+  if (!_platform)
+    throw new Error("No platform registered. Call registerPlatform() before starting Studio.");
+  return _platform;
+}
+
+/** @returns {boolean} */
+export function hasPlatform() {
+  return _platform !== null;
+}

package/src/platforms/devserver.js

@@ -0,0 +1,293 @@
+/**
+ * Devserver.js — Dev Server Platform Adapter
+ *
+ * Implements the StudioPlatform interface for the @jxplatform/server development workflow. All file
+ * I/O goes through /__studio/* REST endpoints. Project opening uses the Chrome File System Access
+ * API (showDirectoryPicker).
+ *
+ * See spec/desktop.md §8 for the full specification.
+ */
+
+/**
+ * Create a DevServerPlatform instance.
+ *
+ * The adapter is stateless apart from `_projectRoot`, which tracks the server-relative project
+ * directory (e.g. "examples/site-demo"). All paths passed INTO PAL methods are project-relative;
+ * the adapter prefixes them with `_projectRoot` before hitting the server, and strips the prefix
+ * from responses.
+ */
+export function createDevServerPlatform() {
+  let _projectRoot = ".";
+
+  /**
+   * Prefix a project-relative path with the active project root for server API calls.
+   *
+   * @param {string} rel
+   */
+  function serverPath(rel) {
+    if (!_projectRoot || _projectRoot === ".") return rel;
+    return rel === "." ? _projectRoot : `${_projectRoot}/${rel}`;
+  }
+
+  /**
+   * Strip the project root prefix from a server-root-relative path.
+   *
+   * @param {string} path
+   */
+  function stripRoot(path) {
+    if (!_projectRoot || _projectRoot === ".") return path;
+    return path.startsWith(_projectRoot + "/") ? path.slice(_projectRoot.length + 1) : path;
+  }
+
+  return {
+    id: "devserver",
+
+    /** Get or set the current project root (server-relative path). */
+    get projectRoot() {
+      return _projectRoot;
+    },
+    set projectRoot(v) {
+      _projectRoot = v || ".";
+    },
+
+    // ─── Project opening ──────────────────────────────────────────────────
+
+    async openProject() {
+      // Use Chrome's showDirectoryPicker API
+      if (!("showDirectoryPicker" in window)) {
+        throw new Error("showDirectoryPicker not available — use a Chromium-based browser");
+      }
+
+      let dirHandle;
+      try {
+        dirHandle = await /** @type {any} */ (window).showDirectoryPicker({ mode: "readwrite" });
+      } catch (/** @type {any} */ e) {
+        // User cancelled the picker
+        if (e.name === "AbortError") return null;
+        throw e;
+      }
+
+      // Read project.json from the chosen directory
+      let siteHandle;
+      try {
+        siteHandle = await dirHandle.getFileHandle("project.json");
+      } catch {
+        throw new Error("No project.json found in selected folder");
+      }
+
+      const file = await siteHandle.getFile();
+      const config = JSON.parse(await file.text());
+
+      // Resolve server-relative path by matching against known sites
+      const sitesRes = await fetch("/__studio/sites");
+      if (!sitesRes.ok) throw new Error("Failed to fetch site list from server");
+      const sites = await sitesRes.json();
+      const match = sites.find(
+        /** @param {any} s */ (s) => JSON.stringify(s.config) === JSON.stringify(config),
+      );
+
+      if (!match) {
+        throw new Error("Selected project is not under the dev server root");
+      }
+
+      _projectRoot = match.path;
+
+      return {
+        config,
+        handle: {
+          root: match.path,
+          name: config.name || match.path.split("/").pop(),
+          projectConfig: config,
+        },
+      };
+    },
+
+    /**
+     * Probe the server root to see if it is itself a site project. Used at startup to auto-detect
+     * projects.
+     */
+    async probeRootProject() {
+      try {
+        const [projectRes, infoRes] = await Promise.all([
+          fetch("/__studio/project"),
+          fetch("/__studio/project-info?dir=."),
+        ]);
+        const meta = projectRes.ok ? await projectRes.json() : { root: ".", name: "project" };
+        const info = infoRes.ok ? await infoRes.json() : { isSiteProject: false };
+        return { meta, info };
+      } catch {
+        return null;
+      }
+    },
+
+    // ─── File operations ──────────────────────────────────────────────────
+
+    /** @param {string} dir */
+    async listDirectory(dir) {
+      const res = await fetch(`/__studio/files?dir=${encodeURIComponent(serverPath(dir))}`);
+      if (!res.ok) throw new Error(`Failed to list directory: ${dir}`);
+      const entries = await res.json();
+      for (const e of entries) e.path = stripRoot(e.path);
+      return entries;
+    },
+
+    /** @param {string} path */
+    async readFile(path) {
+      const res = await fetch(`/__studio/file?path=${encodeURIComponent(serverPath(path))}`);
+      if (!res.ok) throw new Error(`Failed to read file: ${path}`);
+      const data = await res.json();
+      return data.content;
+    },
+
+    /**
+     * @param {string} path
+     * @param {string} content
+     */
+    async writeFile(path, content) {
+      const res = await fetch(`/__studio/file?path=${encodeURIComponent(serverPath(path))}`, {
+        method: "PUT",
+        body: content,
+      });
+      if (!res.ok) throw new Error(`Failed to write file: ${path}`);
+    },
+
+    /** @param {string} path */
+    async deleteFile(path) {
+      const res = await fetch(`/__studio/file?path=${encodeURIComponent(serverPath(path))}`, {
+        method: "DELETE",
+      });
+      if (!res.ok && res.status !== 404) throw new Error(`Failed to delete file: ${path}`);
+    },
+
+    /**
+     * @param {string} from
+     * @param {string} to
+     */
+    async renameFile(from, to) {
+      const res = await fetch("/__studio/file/rename", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ from: serverPath(from), to: serverPath(to) }),
+      });
+      if (!res.ok) throw new Error(`Failed to rename: ${from} → ${to}`);
+    },
+
+    /** @param {string} _path */
+    async createDirectory(_path) {
+      // The server creates directories implicitly when writing files.
+      // Write a placeholder and delete it, or rely on mkdir behavior.
+      // For now, use the writeFile + delete approach if directory creation
+      // is explicitly needed. The server's writeFile already calls mkdir().
+    },
+
+    // ─── Component discovery ──────────────────────────────────────────────
+
+    /** @param {string} dir */
+    async discoverComponents(dir) {
+      const scanDir = dir || _projectRoot;
+      const url =
+        scanDir === "."
+          ? "/__studio/components"
+          : `/__studio/components?dir=${encodeURIComponent(scanDir)}`;
+      const res = await fetch(url);
+      if (!res.ok) return [];
+      return await res.json();
+    },
+
+    // ─── Package management ──────────────────────────────────────────────
+
+    /** @param {string} name */
+    async addPackage(name) {
+      const res = await fetch("/__studio/packages/add", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ name }),
+      });
+      if (!res.ok) throw new Error(await res.text());
+      return await res.json();
+    },
+
+    /** @param {string} name */
+    async removePackage(name) {
+      const res = await fetch("/__studio/packages/remove", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ name }),
+      });
+      if (!res.ok) throw new Error(await res.text());
+      return await res.json();
+    },
+
+    async listPackages() {
+      const res = await fetch("/__studio/packages");
+      if (!res.ok) return [];
+      return await res.json();
+    },
+
+    // ─── Code services (optional) ─────────────────────────────────────────
+
+    /**
+     * @param {string} action
+     * @param {any} payload
+     */
+    async codeService(action, payload) {
+      try {
+        const res = await fetch(`/__studio/code/${action}`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify(payload),
+        });
+        if (!res.ok) return null;
+        return await res.json();
+      } catch {
+        return null;
+      }
+    },
+
+    // ─── Site context resolution ──────────────────────────────────────
+
+    /**
+     * Given an absolute file path, walk up to find the nearest project.json ancestor. Returns {
+     * sitePath, projectConfig } or { sitePath: null }.
+     *
+     * @param {string} filePath — absolute system path
+     */
+    async resolveSiteContext(filePath) {
+      const res = await fetch(`/__studio/resolve-site?path=${encodeURIComponent(filePath)}`);
+      if (!res.ok) return { sitePath: null };
+      return await res.json();
+    },
+
+    // ─── File location ────────────────────────────────────────────────────
+
+    /** @param {string} name */
+    async locateFile(name) {
+      try {
+        const res = await fetch("/__studio/locate", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ name }),
+        });
+        if (res.ok) return (await res.json()).path || null;
+      } catch {}
+      return null;
+    },
+
+    // ─── Plugin schema ────────────────────────────────────────────────────
+
+    /**
+     * @param {string} src
+     * @param {string} prototype
+     * @param {string} base
+     */
+    async fetchPluginSchema(src, prototype, base) {
+      const params = new URLSearchParams({ src });
+      if (prototype) params.set("prototype", prototype);
+      if (base) params.set("base", base);
+      const res = await fetch(`/__studio/plugin-schema?${params}`);
+      if (!res.ok) return null;
+      const { schema } = await res.json();
+      return schema;
+    },
+  };
+}

package/src/services/cem-export.js

@@ -0,0 +1,130 @@
+/** Collect slot elements from the document tree. */
+export function collectSlots(/** @type {any} */ node, /** @type {any} */ slots = []) {
+  if (node?.tagName === "slot") {
+    slots.push(node.attributes?.name || "");
+  }
+  if (Array.isArray(node?.children))
+    node.children.forEach((/** @type {any} */ c) => collectSlots(c, slots));
+  return slots;
+}
+
+/**
+ * Generate and download a CEM 2.1.0 manifest for the current document.
+ *
+ * @param {any} S - Studio state
+ * @param {{
+ *   defCategory: (d: any) => string;
+ *   normParam: (p: any) => any;
+ *   collectCssParts: (node: any) => any[];
+ * }} helpers
+ */
+export function exportCemManifest(S, helpers) {
+  const { defCategory, normParam, collectCssParts } = helpers;
+  const doc = S.document;
+  const tagName = doc.tagName;
+  if (!tagName || !tagName.includes("-")) return;
+
+  const state = doc.state || {};
+  const members = [];
+  const attributes = [];
+  const events = [];
+  const seenEvents = new Set();
+
+  for (const [key, d] of Object.entries(state)) {
+    if (key.startsWith("#")) continue; // private
+
+    const cat = defCategory(d);
+
+    if (cat === "function") {
+      members.push({
+        kind: "method",
+        name: key,
+        ...(d.description ? { description: d.description } : {}),
+        ...(d.parameters ? { parameters: d.parameters.map(normParam) } : {}),
+        ...(d.deprecated
+          ? { deprecated: typeof d.deprecated === "string" ? d.deprecated : true }
+          : {}),
+      });
+      // Collect emits
+      if (Array.isArray(d.emits)) {
+        for (const ev of d.emits) {
+          if (ev.name && !seenEvents.has(ev.name)) {
+            seenEvents.add(ev.name);
+            events.push({
+              name: ev.name,
+              ...(ev.type ? { type: ev.type } : {}),
+              ...(ev.description ? { description: ev.description } : {}),
+            });
+          }
+        }
+      }
+    } else if (cat === "state") {
+      members.push({
+        kind: "field",
+        name: key,
+        ...(d.type ? { type: { text: d.type } } : {}),
+        ...(d.default !== undefined ? { default: String(d.default) } : {}),
+        ...(d.description ? { description: d.description } : {}),
+        ...(d.attribute ? { attribute: d.attribute } : {}),
+        ...(d.reflects ? { reflects: true } : {}),
+        ...(d.deprecated
+          ? { deprecated: typeof d.deprecated === "string" ? d.deprecated : true }
+          : {}),
+      });
+      if (d.attribute) {
+        attributes.push({
+          name: d.attribute,
+          ...(d.type ? { type: { text: d.type } } : {}),
+          fieldName: key,
+        });
+      }
+    }
+  }
+
+  // Slots
+  const slotNames = collectSlots(doc);
+  const slots = slotNames.map((/** @type {any} */ name) => ({
+    name: name || "",
+    ...(name ? {} : { description: "Default slot" }),
+  }));
+
+  // CSS custom properties
+  const style = doc.style || {};
+  const cssProperties = Object.entries(style)
+    .filter(([k]) => k.startsWith("--"))
+    .map(([name, val]) => ({ name, default: String(val) }));
+
+  // CSS parts
+  const cssParts = collectCssParts(doc).map((p) => ({ name: p.name }));
+
+  const manifest = {
+    schemaVersion: "2.1.0",
+    modules: [
+      {
+        kind: "javascript-module",
+        path: "",
+        declarations: [
+          {
+            kind: "class",
+            name: tagName,
+            tagName,
+            members,
+            ...(attributes.length ? { attributes } : {}),
+            ...(events.length ? { events } : {}),
+            ...(slots.length ? { slots } : {}),
+            ...(cssProperties.length ? { cssProperties } : {}),
+            ...(cssParts.length ? { cssParts } : {}),
+          },
+        ],
+      },
+    ],
+  };
+
+  const blob = new Blob([JSON.stringify(manifest, null, 2)], { type: "application/json" });
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement("a");
+  a.href = url;
+  a.download = `${tagName}.cem.json`;
+  a.click();
+  URL.revokeObjectURL(url);
+}

package/src/services/code-services.js

@@ -0,0 +1,98 @@
+/** OXC code services (server-backed) */
+
+import { getPlatform } from "../platform.js";
+import { getNodeAtPath } from "../store.js";
+import * as monaco from "monaco-editor/esm/vs/editor/editor.api.js";
+
+/**
+ * @param {any} action
+ * @param {any} payload
+ */
+export async function codeService(action, payload) {
+  const platform = getPlatform();
+  if (!platform.codeService) return null;
+  return platform.codeService(action, payload);
+}
+
+/**
+ * Ask the server to locate a document by filename within the project root.
+ *
+ * @param {any} name
+ */
+export async function locateDocument(name) {
+  const platform = getPlatform();
+  if (!platform.locateFile) return null;
+  return platform.locateFile(name);
+}
+
+/** Cache of plugin schemas keyed by "$src::$prototype". */
+export const pluginSchemaCache = new Map();
+
+/**
+ * Fetch and cache the schema for an external $prototype + $src module via the server.
+ *
+ * @param {any} def
+ * @param {any} state
+ */
+export async function fetchPluginSchema(def, state) {
+  if (!def.$src || !def.$prototype) return null;
+  const cacheKey = `${def.$src}::${def.$prototype}`;
+  if (pluginSchemaCache.has(cacheKey)) return pluginSchemaCache.get(cacheKey);
+
+  try {
+    const platform = getPlatform();
+    if (!platform.fetchPluginSchema) {
+      pluginSchemaCache.set(cacheKey, null);
+      return null;
+    }
+    const base = state.documentPath ? `${location.origin}/${state.documentPath}` : undefined;
+    const schema = await platform.fetchPluginSchema(def.$src, def.$prototype, base);
+    pluginSchemaCache.set(cacheKey, schema);
+    return schema;
+  } catch {
+    pluginSchemaCache.set(cacheKey, null);
+    return null;
+  }
+}
+
+/**
+ * @param {any} editor
+ * @param {any[]} diagnostics
+ */
+export function setLintMarkers(editor, diagnostics) {
+  const model = editor.getModel();
+  if (!model) return;
+  const markers = diagnostics
+    .map((d) => {
+      const label = d.labels?.[0];
+      if (!label) return null;
+      const { line, column, length } = label.span;
+      return {
+        severity:
+          d.severity === "error" ? monaco.MarkerSeverity.Error : monaco.MarkerSeverity.Warning,
+        message: d.message + (d.help ? `\n${d.help}` : ""),
+        startLineNumber: line,
+        startColumn: column,
+        endLineNumber: line,
+        endColumn: column + (length || 1),
+        code: d.url ? { value: d.code, target: monaco.Uri.parse(d.url) } : d.code,
+        source: "oxlint",
+      };
+    })
+    .filter(Boolean);
+  monaco.editor.setModelMarkers(model, "oxlint", /** @type {any} */ (markers));
+}
+
+/**
+ * @param {any} editing
+ * @param {any} state
+ */
+export function getFunctionArgs(editing, state) {
+  if (editing.type === "def") {
+    return state.document.state?.[editing.defName]?.parameters || ["state", "event"];
+  } else if (editing.type === "event") {
+    const node = getNodeAtPath(state.document, editing.path);
+    return node?.[editing.eventKey]?.parameters || ["state", "event"];
+  }
+  return ["state", "event"];
+}