@jxsuite/schema 1.8.0 → 1.9.0

package/package.json

@@ -10,6 +10,7 @@
   "exports": {
     ".": "./src/schema.ts",
     "./asset-paths": "./src/asset-paths.ts",
+    "./component-meta": "./src/component-meta.ts",
     "./extension-registry": "./src/extension-registry.ts",
     "./format-registry": "./src/format-registry.ts",
     "./project-schemas": "./src/project-schemas.ts",
@@ -54,7 +55,7 @@
     "upgrade": "bunx npm-check-updates -u && bun install"
   },
   "type": "module",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "devDependencies": {
     "json-schema-to-ts": "^3.1.1"
   }

package/src/asset-paths.ts

@@ -196,3 +196,345 @@ export function collectAssetUrls(text: string, mounts: readonly AssetMount[]): s
   }
   return [...found].filter(Boolean);
 }
+
+// ─── Project paths ↔ site URLs (specs/site-architecture.md §9.3) ─────────────
+
+/**
+ * The project directory whose contents publish at the site root.
+ *
+ * A convention rather than a setting: `public/logo.png` is `/logo.png` on the built site, which is
+ * why an authored `/logo.png` names a file the project tree calls something else.
+ */
+export const PUBLIC_DIR = "public";
+
+/** Node keys whose value is a media reference. Mirrors `ASSET_KEYS` in the content loader. */
+export const ASSET_KEYS = ["src", "poster"] as const;
+
+/**
+ * One step in a host's resolution order for a site-absolute URL.
+ *
+ * - `"mounts"` — an extension asset mount publishes a directory at a URL prefix (extensions.md §8.5).
+ * - `"root"` — the URL path is a project-relative path as written.
+ * - `"public"` — the URL path is relative to {@link PUBLIC_DIR}.
+ */
+export type AssetLane = "mounts" | "root" | "public";
+
+/**
+ * What a BUILD resolves — mounts, then `public/`, and nothing else.
+ *
+ * This is the published contract (site-architecture.md §9.3): a file at `<root>/hero.jpg` is not
+ * addressable at `/hero.jpg` on a deployed site, because nothing copies it there.
+ */
+export const BUILD_LANES: readonly AssetLane[] = ["mounts", "public"];
+
+/**
+ * What the editing servers resolve — mounts, then the project root, then `public/`.
+ *
+ * It is deliberately NOT {@link BUILD_LANES}, and the difference is a real one rather than an
+ * implementation detail: `serveProjectFile` in `@jxsuite/server` tries the project root BEFORE
+ * `public/`, so `<root>/hero.jpg` loads at `/hero.jpg` in a preview and 404s in production. A test
+ * asserts the two constants differ, so nobody can quietly assume they agree.
+ */
+export const DEV_SERVER_LANES: readonly AssetLane[] = ["mounts", "root", "public"];
+
+/**
+ * Split a reference into the path part and the `?query#hash` suffix.
+ *
+ * The suffix must survive every rewrite untouched: `./hero.png?v=2` is one file plus a
+ * cache-buster, and a rewrite that drops the buster changes what the browser requests.
+ *
+ * @param {string} value - An authored reference
+ * @returns {{ path: string; suffix: string }} The bare path and everything from the first `?`/`#`
+ */
+export function splitRefSuffix(value: string): { path: string; suffix: string } {
+  const cut = value.search(/[#?]/);
+  return cut === -1
+    ? { path: value, suffix: "" }
+    : { path: value.slice(0, cut), suffix: value.slice(cut) };
+}
+
+/**
+ * True when `value` is already a URL, a template, a fragment, or empty — never a project file.
+ *
+ * Mirrors `isNonRelativeRef` in the content loader. A root-relative `/hero.jpg` counts as
+ * non-relative here because it is a SITE URL, not a path relative to the document.
+ *
+ * @param {string} value - An authored reference
+ * @returns {boolean}
+ */
+export function isNonRelativeRef(value: string): boolean {
+  return (
+    value === "" ||
+    value.startsWith("/") ||
+    value.startsWith("#") ||
+    value.includes("${") ||
+    /^[a-z][\w+.-]*:/i.test(value)
+  );
+}
+
+/**
+ * Normalize a project-relative path: forward slashes, no `./` prefix, no leading or trailing slash.
+ *
+ * @param {string} path - A project-relative path in any spelling
+ * @returns {string} The canonical spelling
+ */
+export function normalizeProjectPath(path: string): string {
+  return path.replaceAll("\\", "/").replace(/^\.\//, "").replace(/^\/+/, "").replace(/\/+$/, "");
+}
+
+/** The directory portion of a project-relative path (`""` for a root-level file). */
+export function dirOfPath(path: string): string {
+  const normalized = normalizeProjectPath(path);
+  const slash = normalized.lastIndexOf("/");
+  return slash === -1 ? "" : normalized.slice(0, slash);
+}
+
+/**
+ * Resolve `ref` against `dir` in a pure, POSIX-ish way — no `node:path`, and no leading-slash
+ * assumption, because project paths are relative to a root the browser does not have.
+ *
+ * @param {string} dir - Project-relative directory (`""` for the root)
+ * @param {string} ref - A relative reference
+ * @returns {string | null} The project-relative result, or null when it climbs above the root
+ */
+export function joinProjectPath(dir: string, ref: string): string | null {
+  const base = dir === "" || dir === "." ? [] : normalizeProjectPath(dir).split("/");
+  const out = base.filter((segment) => segment !== "" && segment !== ".");
+  for (const segment of ref.replaceAll("\\", "/").split("/")) {
+    if (segment === "" || segment === ".") {
+      continue;
+    }
+    if (segment === "..") {
+      if (out.length === 0) {
+        return null; // Escapes the project root.
+      }
+      out.pop();
+      continue;
+    }
+    out.push(segment);
+  }
+  return out.join("/");
+}
+
+/**
+ * The site URL a project file publishes at under `lanes`, or null when nothing publishes it.
+ *
+ * The lanes are tried in order, so the answer is the URL the host would resolve FIRST — which is
+ * what makes {@link projectPathsForSiteUrl} its inverse. Under {@link DEV_SERVER_LANES} that means
+ * `public/logo.png` answers `/public/logo.png` (the root lane, which the server tries first) rather
+ * than `/logo.png`; both work there, and only one round-trips.
+ *
+ * @param {string} path - Project-relative path
+ * @param {readonly AssetMount[]} mounts - Project-relative asset mounts
+ * @param {readonly AssetLane[]} lanes - The host's resolution order
+ * @returns {string | null} A site-absolute URL, or null
+ */
+export function siteUrlForPath(
+  path: string,
+  mounts: readonly AssetMount[],
+  lanes: readonly AssetLane[],
+): string | null {
+  const normalized = normalizeProjectPath(path);
+  if (normalized === "") {
+    return null;
+  }
+  for (const lane of lanes) {
+    if (lane === "mounts") {
+      const url = assetUrlFor(mounts, normalized);
+      if (url) {
+        return url;
+      }
+      continue;
+    }
+    if (lane === "root") {
+      return `/${encodeProjectPath(normalized)}`;
+    }
+    if (normalized === PUBLIC_DIR || normalized.startsWith(`${PUBLIC_DIR}/`)) {
+      return `/${encodeProjectPath(normalized.slice(PUBLIC_DIR.length + 1))}`;
+    }
+  }
+  return null;
+}
+
+/**
+ * Every project path a site-absolute URL could name under `lanes`, in the order the host tries
+ * them.
+ *
+ * A list rather than one answer because the lanes genuinely overlap: `/hero.jpg` is `hero.jpg` to
+ * the root lane and `public/hero.jpg` to the public lane, and only a filesystem can say which
+ * exists. Callers with no filesystem — the Studio canvas — take the first.
+ *
+ * @param {string} url - A site-absolute URL (query and hash are ignored)
+ * @param {readonly AssetMount[]} mounts - Project-relative asset mounts
+ * @param {readonly AssetLane[]} lanes - The host's resolution order
+ * @returns {string[]} Candidate project-relative paths, most-preferred first
+ */
+export function projectPathsForSiteUrl(
+  url: string,
+  mounts: readonly AssetMount[],
+  lanes: readonly AssetLane[],
+): string[] {
+  const { path } = splitRefSuffix(url);
+  if (!path.startsWith("/")) {
+    return [];
+  }
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(path);
+  } catch {
+    return [];
+  }
+  // A still-encoded dot or slash after one decode is a traversal attempt, not a filename.
+  if (/%2e|%2f/i.test(decoded)) {
+    return [];
+  }
+  const rest = decoded.replace(/^\/+/, "");
+  if (rest === "" || rest.split("/").some((segment) => segment === "." || segment === "..")) {
+    return [];
+  }
+  const out: string[] = [];
+  for (const lane of lanes) {
+    if (lane === "mounts") {
+      const mounted = resolveAssetUrl(mounts, path);
+      // Only a mount INSIDE the project is addressable by path; `../../docs` is not.
+      if (mounted !== null && !mounted.startsWith("/") && !/^[A-Za-z]:/.test(mounted)) {
+        out.push(normalizeProjectPath(mounted));
+      }
+      continue;
+    }
+    out.push(lane === "root" ? rest : `${PUBLIC_DIR}/${rest}`);
+  }
+  return [...new Set(out)];
+}
+
+/**
+ * The project file an authored reference names, seen from the document that wrote it.
+ *
+ * The two shapes an author writes resolve differently and neither goes through a site URL:
+ *
+ * - A content-relative `./images/hero.png` resolves against the document's own directory, which IS a
+ *   project path already — `content/posts/images/hero.png`. The mount detour that the built site
+ *   performs is not needed to name the file, only to publish it.
+ * - A root-relative `/hero.jpg` is a site URL, so it resolves through {@link projectPathsForSiteUrl}
+ *   and takes the host's first lane.
+ *
+ * Everything else — an absolute URL, a `data:` URI, a `${…}` template, a bare fragment — names no
+ * project file and returns null, which callers read as "leave it exactly as written".
+ *
+ * @param {string} value - The authored reference
+ * @param {string} documentDir - Project-relative directory of the document that wrote it
+ * @param {readonly AssetMount[]} mounts - Project-relative asset mounts
+ * @param {readonly AssetLane[]} lanes - The host's resolution order
+ * @returns {string | null} A project-relative path, or null
+ */
+export function projectPathForRef(
+  value: string,
+  documentDir: string,
+  mounts: readonly AssetMount[],
+  lanes: readonly AssetLane[],
+): string | null {
+  const { path } = splitRefSuffix(value);
+  if (path === "") {
+    return null;
+  }
+  if (isNonRelativeRef(value)) {
+    return path.startsWith("/") ? (projectPathsForSiteUrl(path, mounts, lanes)[0] ?? null) : null;
+  }
+  // A reference ending in a slash names a DIRECTORY, and no directory is a media file.
+  if (path.endsWith("/")) {
+    return null;
+  }
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(path);
+  } catch {
+    return null;
+  }
+  const joined = joinProjectPath(documentDir, decoded);
+  if (joined === null || joined === "" || joined === normalizeProjectPath(documentDir)) {
+    return null;
+  }
+  return joined;
+}
+
+/**
+ * Percent-encode each path segment so the result survives an HTML attribute.
+ *
+ * Segment by segment, so the separators stay separators: `encodeURIComponent` on the whole path
+ * would turn every `/` into `%2F` and produce one very long filename.
+ *
+ * @param {string} path - A project-relative path
+ * @returns {string} The same path, each segment encoded
+ */
+export function encodeProjectPath(path: string): string {
+  return path
+    .split("/")
+    .map((segment) => encodeURIComponent(segment))
+    .join("/");
+}
+
+// ─── srcset ──────────────────────────────────────────────────────────────────
+
+/** One `srcset` candidate: a URL and the descriptor that selects it (`""` when there is none). */
+export interface SrcsetCandidate {
+  url: string;
+  descriptor: string;
+}
+
+/**
+ * Parse a `srcset` attribute into its candidates.
+ *
+ * Splitting on `","` is wrong and quietly so: a `data:` URL contains commas, and so does any URL
+ * with a query list. This follows HTML's own algorithm instead — collect non-whitespace as the URL,
+ * and if it ends in commas, the descriptor is empty and the next candidate starts immediately.
+ *
+ * @param {string} value - The attribute value
+ * @returns {SrcsetCandidate[]} Candidates in source order
+ */
+export function parseSrcset(value: string): SrcsetCandidate[] {
+  const out: SrcsetCandidate[] = [];
+  let i = 0;
+  while (i < value.length) {
+    while (i < value.length && (/\s/.test(value[i]!) || value[i] === ",")) {
+      i += 1;
+    }
+    if (i >= value.length) {
+      break;
+    }
+    const start = i;
+    while (i < value.length && !/\s/.test(value[i]!)) {
+      i += 1;
+    }
+    let url = value.slice(start, i);
+    if (url.endsWith(",")) {
+      out.push({ descriptor: "", url: url.replace(/,+$/, "") });
+      continue;
+    }
+    while (i < value.length && /\s/.test(value[i]!)) {
+      i += 1;
+    }
+    const descStart = i;
+    while (i < value.length && value[i] !== ",") {
+      i += 1;
+    }
+    const descriptor = value.slice(descStart, i).trim();
+    i += 1; // Consume the separating comma.
+    url = url.replace(/,+$/, "");
+    if (url !== "") {
+      out.push({ descriptor, url });
+    }
+  }
+  return out;
+}
+
+/**
+ * Serialize candidates back into a `srcset` attribute value.
+ *
+ * @param {readonly SrcsetCandidate[]} candidates
+ * @returns {string} The attribute value
+ */
+export function formatSrcset(candidates: readonly SrcsetCandidate[]): string {
+  return candidates
+    .map(({ url, descriptor }) => (descriptor ? `${url} ${descriptor}` : url))
+    .join(", ");
+}

package/src/component-meta.ts

@@ -0,0 +1,143 @@
+/**
+ * Component metadata, derived from a parsed component document.
+ *
+ * Discovery — "what components does this project have, and what props do they take" — is a pure
+ * function of the document. It reads `tagName`, `state` and any `<slot>` in the tree; it executes
+ * nothing. That distinction is what lets a backend with a no-project-JS posture discover JSON
+ * components safely, which Jx Cloud could not do while this logic lived inside two Bun servers.
+ *
+ * It lives here because THREE backends need the same answer and two of them had already written it
+ * twice: `packages/server/src/studio-api.ts` (the dev server's `/__studio/components`) and
+ * `packages/desktop/src/project-session.ts`. A third copy in the cloud adapter would have made
+ * "which entries in `state` count as props" a question with three answers.
+ *
+ * @license MIT
+ */
+
+import type { JsonValue } from "../types";
+
+/** One `<slot>` found in a component's tree. */
+export interface ComponentSlotDef {
+  /** The slot's name; `""` for the unnamed slot. */
+  name: string;
+  /** Fallback children rendered when nothing is slotted in. */
+  fallback?: unknown[];
+}
+
+/** One editable prop, derived from a `state` entry. */
+export interface ComponentPropDef {
+  name: string;
+  type?: unknown;
+  default?: JsonValue;
+  format?: unknown;
+}
+
+/** What discovery reports for one component document. */
+export interface ComponentMetaOut {
+  tagName: string;
+  $id: string | null;
+  path: string;
+  props: ComponentPropDef[];
+  slots?: ComponentSlotDef[];
+  hasElements: boolean;
+}
+
+/**
+ * Collect slot definitions from a parsed component tree.
+ *
+ * Whitespace-only names count as unnamed (`""`), and only static `children` arrays are walked — a
+ * slot produced by a `$map` or a `$switch` has no fixed identity to report.
+ *
+ * @param {unknown} node - A node of the component document.
+ * @param {ComponentSlotDef[]} [out] - Accumulator, for the recursive walk.
+ * @returns {ComponentSlotDef[]}
+ */
+export function collectSlotDefs(node: unknown, out: ComponentSlotDef[] = []): ComponentSlotDef[] {
+  if (!node || typeof node !== "object" || Array.isArray(node)) {
+    return out;
+  }
+  const el = node as Record<string, unknown>;
+  if (el.tagName === "slot") {
+    const attrs = el.attributes as Record<string, unknown> | undefined;
+    const rawName = attrs?.name;
+    const name = typeof rawName === "string" ? rawName.trim() : "";
+    const { children } = el;
+    out.push({
+      name,
+      ...(Array.isArray(children) && children.length > 0 ? { fallback: children } : {}),
+    });
+  }
+  if (Array.isArray(el.children)) {
+    for (const c of el.children) {
+      collectSlotDefs(c, out);
+    }
+  }
+  return out;
+}
+
+/**
+ * Whether a `state` entry is an editable prop.
+ *
+ * The shorthand form (`"title": "Hello"`) always is. The full form is one only when it is plain
+ * data: a computed value, a handler or a prototype entry is machinery the author does not type
+ * into, and offering it as a prop would put a text box in front of a function.
+ *
+ * @param {unknown} def - The `state` entry.
+ * @returns {boolean}
+ */
+function isPropEntry(def: unknown): boolean {
+  if (def == null) {
+    return false;
+  }
+  if (typeof def !== "object") {
+    return true;
+  }
+  const obj = def as Record<string, unknown>;
+  return !obj.$prototype && !obj.$handler && !obj.$compute;
+}
+
+/**
+ * Metadata for one component document, or null when the document is not a component.
+ *
+ * A component is a document whose `tagName` is a valid custom-element name — it must contain a
+ * hyphen. That single test is what keeps a page or a data file from being reported as a component
+ * when a whole project tree is scanned.
+ *
+ * @param {unknown} doc - The parsed document.
+ * @param {string} path - Project-relative path, reported verbatim.
+ * @returns {ComponentMetaOut | null}
+ */
+export function componentMetaFrom(doc: unknown, path: string): ComponentMetaOut | null {
+  if (!doc || typeof doc !== "object" || Array.isArray(doc)) {
+    return null;
+  }
+  const content = doc as Record<string, unknown>;
+  const { tagName } = content;
+  if (typeof tagName !== "string" || !tagName.includes("-")) {
+    return null;
+  }
+  const slots = collectSlotDefs(content);
+  const state = (content.state ?? {}) as Record<string, unknown>;
+  return {
+    $id: typeof content.$id === "string" && content.$id ? content.$id : null,
+    hasElements: Array.isArray(content.$elements) && content.$elements.length > 0,
+    path,
+    props: Object.entries(state)
+      .filter(([, def]) => isPropEntry(def))
+      .map(([name, def]) => {
+        if (typeof def !== "object" || def === null) {
+          // Shorthand: the value IS the default, and its runtime type is the only type on offer.
+          return { default: def as JsonValue, name, type: typeof def };
+        }
+        const obj = def as Record<string, unknown>;
+        return {
+          default: obj.default as JsonValue,
+          format: obj.format,
+          name,
+          type: obj.type,
+        };
+      }),
+    ...(slots.length > 0 ? { slots } : {}),
+    tagName,
+  };
+}