@jxsuite/studio 2.0.0 → 2.1.0

package/src/files/fs-events.ts

@@ -9,6 +9,7 @@
  */
 
 import { getPlatform } from "../platform";
+import { invalidateUsages } from "../services/references";
 import { projectState } from "../store";
 import type { DirEntry, FsEvent } from "../types";
 
@@ -116,6 +117,15 @@ export interface FsSyncContext {
   renderLeftPanel: () => void;
   /** Optional hook for an external content change to an open file (e.g. reload a clean tab). */
   onContentChange?: (path: string) => void;
+  /**
+   * Drop every cache keyed on "what files the project contains".
+   *
+   * Passed in rather than imported, for the reason `renderLeftPanel` is: the caches live in panels,
+   * and this module is imported BY the file layer those panels sit on top of — reaching up would be
+   * a cycle. The bootstrap owns the list because the bootstrap is where the panels are already in
+   * scope.
+   */
+  invalidateDerivedCaches?: () => void;
 }
 
 /**
@@ -153,6 +163,17 @@ export function startFsSync(ctx: FsSyncContext): () => void {
   };
 
   return platform.subscribeFileEvents((events) => {
+    // Before the echo filter, deliberately. `isRecentLocal` drops the events Studio caused, which
+    // Is right for the tree (it already repainted) and wrong for a DERIVED cache — Studio's own
+    // Write changes what the project contains exactly as much as anyone else's does.
+    //
+    // Every cache keyed on "what files exist" is dropped here, in one place, because they answer
+    // One event. Each one had an invalidator and no caller, and each stale answer is visible: the
+    // Link-target picker offering a route whose page was deleted, the layout picker attributing a
+    // Removed layout's `$head` to the open page, a `$paths` enumeration listing entries that are
+    // Gone.
+    invalidateUsages();
+    ctx.invalidateDerivedCaches?.();
     pending.push(...events);
     if (timer) {
       clearTimeout(timer);

package/src/files/media-meta.ts

@@ -0,0 +1,203 @@
+/**
+ * Media metadata — what a file IS, for surfaces that show media rather than resolve it.
+ *
+ * Three facts, and each has an "unknown" that is not a zero:
+ *
+ * - **Size and modified time** come from the directory listing the caller already performed. A media
+ *   surface enumerates a directory to draw itself, so `seedMediaMeta` folds those entries in for
+ *   free and {@link loadMediaMeta} is the fallback for a path nobody enumerated.
+ * - **Pixel dimensions** are OPPORTUNISTIC. There is no stat that returns them and no decoder in the
+ *   shell, so the only honest source is an `<img>` that already loaded — which every media surface
+ *   renders anyway. {@link recordImageSize} is how that surface hands the number back, and until
+ *   one does, the dimensions are `null` and the summary simply omits them. Downloading the file a
+ *   second time to measure it would be a network request per thumbnail for a line of text.
+ *
+ * A missing number is `null` everywhere, never `0`. `0 × 0` and `0 B` are things a real file can
+ * almost be, so they must not double as "we did not find out" — the same rule
+ * `services/references.ts` applies to a count it cannot answer.
+ *
+ * The cache is dropped wholesale by {@link invalidateMediaMeta}, wired to the same post-upload
+ * invalidation the media picker's listing uses. There is no TTL: a size that expires on a timer is
+ * wrong at an unannounced moment.
+ *
+ * @docs studio/projects/media
+ */
+
+import { getPlatform } from "../platform";
+import { baseName, dirName, normalizeProjectPath } from "./media-paths";
+import { extensionOf, mediaKind } from "./media-upload";
+import type { AssetKind } from "./media-upload";
+import type { DirEntry } from "../types";
+
+/** Everything a media surface can say about one file without opening it. */
+export interface MediaMeta {
+  /** Project-relative, forward-slashed. */
+  path: string;
+  /** Filename only. */
+  name: string;
+  /** Lowercased extension including the dot, or `""`. */
+  ext: string;
+  /** What kind of element it wants to become — the same classification `uploadAssets` records. */
+  kind: AssetKind;
+  /** Bytes on disk, or null when the listing did not say. */
+  bytes: number | null;
+  /** ISO modification time, or null when the listing did not say. */
+  modified: string | null;
+  /** Intrinsic width in CSS pixels, or null until an `<img>` for this file has loaded. */
+  width: number | null;
+  /** Intrinsic height in CSS pixels, or null until an `<img>` for this file has loaded. */
+  height: number | null;
+}
+
+/** Settled metadata, by project-relative path. */
+const settled = new Map<string, MediaMeta>();
+/** In-flight listings, so N surfaces asking about one path share one round trip. */
+const inFlight = new Map<string, Promise<MediaMeta>>();
+/**
+ * Dimensions reported by a loaded `<img>`, kept beside the cache rather than inside it.
+ *
+ * A surface can measure a thumbnail before anyone asks for its size — and a `loadMediaMeta` that
+ * landed afterwards would otherwise overwrite the one fact that cost a decode to learn.
+ */
+const measured = new Map<string, { width: number; height: number }>();
+
+/** Build a meta record from a path and whatever the listing knew about it. */
+function metaFrom(path: string, entry: DirEntry | undefined): MediaMeta {
+  const name = baseName(path);
+  const dims = measured.get(path);
+  return {
+    bytes: typeof entry?.size === "number" ? entry.size : null,
+    ext: extensionOf(name),
+    height: dims?.height ?? null,
+    kind: mediaKind({ name }),
+    modified: entry?.modified ?? null,
+    name,
+    path,
+    width: dims?.width ?? null,
+  };
+}
+
+/**
+ * The metadata known right now, WITHOUT starting a request.
+ *
+ * Templates call this: a lit render is synchronous, and a render that listed a directory every time
+ * it ran would re-list on its own repaint.
+ */
+export function peekMediaMeta(path: string): MediaMeta | null {
+  return settled.get(normalizeProjectPath(path)) ?? null;
+}
+
+/**
+ * Fold a directory listing into the cache — the cheap path, for a surface that just enumerated.
+ *
+ * Only file entries are recorded, and an entry never overwrites a settled record: the listing that
+ * arrives second is not more truthful than the one that arrived first, and replacing the record
+ * would drop measured dimensions from the object templates are already holding.
+ */
+export function seedMediaMeta(entries: Iterable<DirEntry>): void {
+  for (const entry of entries) {
+    if (entry.type !== "file") {
+      continue;
+    }
+    const path = normalizeProjectPath(entry.path);
+    if (!settled.has(path)) {
+      settled.set(path, metaFrom(path, entry));
+    }
+  }
+}
+
+/**
+ * Ask for one file's metadata, or join the ask already in flight.
+ *
+ * Never rejects. A directory that cannot be listed yields a record whose numbers are `null` — "we
+ * do not know how big it is" is a renderable answer, and a thrown error at this altitude would only
+ * be caught and turned back into one by every caller.
+ */
+export async function loadMediaMeta(path: string): Promise<MediaMeta> {
+  const key = normalizeProjectPath(path);
+  const done = settled.get(key);
+  if (done) {
+    return done;
+  }
+  const running = inFlight.get(key);
+  if (running) {
+    return running;
+  }
+  const pending = (async (): Promise<MediaMeta> => {
+    let entry: DirEntry | undefined;
+    try {
+      const listing = await getPlatform().listDirectory(dirName(key));
+      entry = listing.find((item) => normalizeProjectPath(item.path) === key);
+    } catch {
+      // Unreadable or not yet created — the size stays unknown rather than becoming zero.
+      entry = undefined;
+    }
+    return metaFrom(key, entry);
+  })();
+  inFlight.set(key, pending);
+  const meta = await pending;
+  inFlight.delete(key);
+  settled.set(key, meta);
+  return meta;
+}
+
+/**
+ * Record the intrinsic size of a file whose `<img>` has loaded.
+ *
+ * @returns Whether this was new information — the caller repaints only when it was, so a template
+ *   that re-renders its thumbnails (and re-fires their `load` from cache) does not loop.
+ */
+export function recordImageSize(path: string, width: number, height: number): boolean {
+  if (!(width > 0 && height > 0)) {
+    return false; // A broken or still-decoding image reports 0 — that is not a measurement.
+  }
+  const key = normalizeProjectPath(path);
+  const known = measured.get(key);
+  if (known && known.width === width && known.height === height) {
+    return false;
+  }
+  measured.set(key, { height, width });
+  const meta = settled.get(key);
+  if (meta) {
+    settled.set(key, { ...meta, height, width });
+  }
+  return true;
+}
+
+/** Drop every cached record and measurement. Called wherever the media listing is invalidated. */
+export function invalidateMediaMeta(): void {
+  settled.clear();
+  measured.clear();
+}
+
+/** `84 KB`, `1.2 MB`, `903 B` — one significant fraction, because this is a caption. */
+export function formatBytes(bytes: number): string {
+  if (bytes < 1024) {
+    return `${bytes} B`;
+  }
+  if (bytes < 1024 * 1024) {
+    return `${Math.round(bytes / 1024)} KB`;
+  }
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/**
+ * The one-line caption a media surface shows: `1200 × 800 · 84 KB`.
+ *
+ * Unknown facts are omitted rather than rendered as a placeholder, so the line shortens instead of
+ * filling with dashes. It is `""` when nothing at all is known, which a template renders as
+ * nothing.
+ */
+export function mediaMetaSummary(meta: MediaMeta | null): string {
+  if (!meta) {
+    return "";
+  }
+  const parts: string[] = [];
+  if (meta.width !== null && meta.height !== null) {
+    parts.push(`${meta.width} × ${meta.height}`);
+  }
+  if (meta.bytes !== null) {
+    parts.push(formatBytes(meta.bytes));
+  }
+  return parts.join(" · ");
+}

package/src/files/media-paths.ts

@@ -0,0 +1,141 @@
+/**
+ * Media path math — the file, the URL it is published at, and the shapes an author writes.
+ *
+ * One media file has up to three names, and they are not interchangeable:
+ *
+ * | name             | example                          | who writes it                      |
+ * | ---------------- | -------------------------------- | ---------------------------------- |
+ * | the FILE         | `public/hero.jpg`                | the file tree, `uploadAssets`      |
+ * | the SITE URL     | `/hero.jpg`                      | the browser, a preview `<img src>` |
+ * | the AUTHORED ref | `/hero.jpg`, `./images/hero.png` | the document on disk               |
+ *
+ * `public/` is served from the site root, so a document that uses `public/hero.jpg` says
+ * `/hero.jpg` — a string that shares not one path segment with the file it names. A content entry
+ * says `./images/hero.png` and the collection loader republishes it at the content type's asset
+ * mount (specs/site-architecture.md §9.3), so the same file can also be named
+ * `/content/blog/images/hero.png` when the collection's `source` is not already `content/blog`.
+ *
+ * **Why this module exists at all.** `findReferences` resolves each authored ref the way the
+ * compiler does — rooted values against the project root, relative ones against the referencing
+ * document — and compares the RESULT to the path it was asked about. Ask it about `public/hero.jpg`
+ * and every `/hero.jpg` in the project resolves to `hero.jpg`, matches nothing, and the answer is a
+ * confident zero. That is the exact shape of bug that makes a delete look safe: seven pages break
+ * and the dialog says nothing else refers to it. {@link authoredRefTargets} is the fix — it
+ * enumerates what an authored reference to this file RESOLVES to, so the query is keyed on the ref
+ * as written rather than on the file as stored.
+ *
+ * Everything here is pure string math over project-relative, forward-slashed paths. The only input
+ * from outside is the open project's content sections, read the same way `content-assets.ts` reads
+ * them.
+ *
+ * @docs studio/projects/media
+ */
+
+import { contentMountFor } from "../canvas/content-assets";
+import { projectState } from "../store";
+import type { AssetMount } from "@jxsuite/schema/asset-paths";
+import type { ContentSectionEntry } from "../types";
+
+/** The directory whose contents are served from the site root. */
+const PUBLIC_DIR = "public";
+
+/**
+ * A project-relative path in the one spelling every function here expects: forward slashes, no `./`
+ * prefix, no leading `/`, no trailing `/`.
+ */
+export function normalizeProjectPath(path: string): string {
+  return path.replaceAll("\\", "/").replace(/^\.\//, "").replace(/^\/+/, "").replace(/\/+$/, "");
+}
+
+/** The filename of a project-relative path. */
+export function baseName(path: string): string {
+  const normalized = normalizeProjectPath(path);
+  const slash = normalized.lastIndexOf("/");
+  return slash === -1 ? normalized : normalized.slice(slash + 1);
+}
+
+/** The directory of a project-relative path, or `"."` for a file at the project root. */
+export function dirName(path: string): string {
+  const normalized = normalizeProjectPath(path);
+  const slash = normalized.lastIndexOf("/");
+  return slash === -1 ? "." : normalized.slice(0, slash);
+}
+
+/** The open project's content sections, or null when no project (or no `content:`) is loaded. */
+function contentSections(): Record<string, ContentSectionEntry> | null {
+  const content = projectState?.projectConfig?.content;
+  return (content as Record<string, ContentSectionEntry> | undefined) ?? null;
+}
+
+/**
+ * The mount that publishes `path`, or null when it is not inside a content collection.
+ *
+ * `contentMountFor` takes a DOCUMENT path, but the test it performs — which collection directory
+ * contains this path — is exactly the one an asset needs, so the media file is passed straight in
+ * rather than duplicating the loop.
+ */
+function mountOf(path: string): AssetMount | null {
+  return contentMountFor(path, contentSections());
+}
+
+/**
+ * The path a content-mounted file is published under, project-root-relative and WITHOUT the leading
+ * slash — `content/blog/images/hero.png` for `posts/images/hero.png` mounted at `/content/blog`.
+ *
+ * Built by string surgery rather than through `assetUrlFor` on purpose: that function
+ * percent-encodes each segment for use in an HTML attribute, and this value is compared against
+ * paths resolved from raw document strings, which are never decoded on the way in.
+ */
+function mountedPath(path: string, mount: AssetMount): string {
+  const prefix = normalizeProjectPath(mount.urlPrefix);
+  return `${prefix}/${path.slice(mount.dir.length + 1)}`;
+}
+
+/**
+ * The site URL a media file is published at — what a preview `<img>` in panel chrome should load.
+ *
+ * `public/` contents are served from the root, a content asset from its collection's mount, and
+ * anything else from its own project-relative path (which is what the dev server serves).
+ */
+export function mediaSiteUrl(path: string): string {
+  const normalized = normalizeProjectPath(path);
+  if (normalized.startsWith(`${PUBLIC_DIR}/`)) {
+    return `/${normalized.slice(PUBLIC_DIR.length + 1)}`;
+  }
+  const mount = mountOf(normalized);
+  return mount ? `/${mountedPath(normalized, mount)}` : `/${normalized}`;
+}
+
+/**
+ * Every path an authored reference to this media file resolves to — the keys a usage query must ask
+ * about, most literal first.
+ *
+ * 1. The file itself. A sibling's `./images/hero.png`, a rooted `/content/blog/images/hero.png` and a
+ *    bare `assets/logo.svg` all land here.
+ * 2. Its served path, for `public/` media. `/hero.jpg` resolves to `hero.jpg`, which is not a file on
+ *    disk and does not need to be — the sweep compares resolved strings, and this is the string
+ *    every reference to a public asset produces.
+ * 3. Its asset-mount path, when a collection's `source` differs from its mount prefix. Identical to
+ *    (1) for the ordinary `content/<type>/` layout, and deduplicated when it is.
+ *
+ * The list is a UNION and is deliberately generous: over-counting a reference makes a delete dialog
+ * more alarming than it needs to be, while missing one makes it lie.
+ */
+export function authoredRefTargets(path: string): string[] {
+  const normalized = normalizeProjectPath(path);
+  if (normalized === "") {
+    return [];
+  }
+  const targets = [normalized];
+  if (normalized.startsWith(`${PUBLIC_DIR}/`)) {
+    targets.push(normalized.slice(PUBLIC_DIR.length + 1));
+  }
+  const mount = mountOf(normalized);
+  if (mount) {
+    const mounted = mountedPath(normalized, mount);
+    if (!targets.includes(mounted)) {
+      targets.push(mounted);
+    }
+  }
+  return targets;
+}

package/src/files/media-upload.ts

@@ -18,7 +18,7 @@
 
 import { errorMessage } from "@jxsuite/schema/parse";
 import { getPlatform } from "../platform";
-import { statusMessage } from "../panels/statusbar";
+import { notify } from "../services/notify";
 import { activeTab } from "../workspace/workspace";
 
 // ─── File classification ─────────────────────────────────────────────────────
@@ -234,12 +234,16 @@ export async function uploadAssets(
       await platform.uploadFile(path, file);
       uploaded.push({ kind: mediaKind(file), name, path, ref: assetRef(path) });
     } catch (error) {
-      statusMessage(`Upload failed: ${file.name} — ${errorMessage(error)}`);
+      notify.error(`Could not upload ${file.name}.`, {
+        detail: errorMessage(error),
+        path,
+        source: "Media",
+      });
     }
   }
 
   if (uploaded.length > 0) {
-    statusMessage(
+    notify.success(
       uploaded.length === 1
         ? `Uploaded ${uploaded[0]!.name} to ${dir}/`
         : `Uploaded ${uploaded.length} files to ${dir}/`,

package/src/files/media-usage.ts

@@ -0,0 +1,189 @@
+/**
+ * Media usage — "which pages use this image?", asked in the shape an author actually wrote.
+ *
+ * `services/references.ts` already answers "where is this used?" for documents, and its answer is
+ * what every destructive confirmation says out loud. Media does not fit through it unmodified, for
+ * one reason: **the reference index resolves refs, and a media file's authored ref usually resolves
+ * somewhere else.** `public/hero.jpg` is written `/hero.jpg`, which the compiler — and therefore
+ * the sweep — resolves to `hero.jpg`. Ask about the file and every reference to it is invisible;
+ * the query succeeds, returns zero, and the delete dialog says nothing else refers to it while
+ * seven pages break. A confident zero is the one answer a destructive dialog must never invent.
+ *
+ * So the query is keyed on the AUTHORED ref. {@link authoredRefTargets} enumerates every path a
+ * reference to this file resolves to — the file, its served path, its asset-mount path — and this
+ * module asks all of them and unions the answers. Everything else is deliberately inherited rather
+ * than re-implemented: the same `loadUsages` cache (so a dialog and a panel asking at once are one
+ * round trip), the same `invalidateUsages` on any filesystem event, the same `usageWarning`
+ * sentence in the confirmation, and the same `usageHeadline` wording on a panel.
+ *
+ * **A partial answer is `failed`, not a total.** If one lane of the union cannot be counted, the
+ * union cannot either — a number assembled from the lanes that worked reads exactly like a complete
+ * one, and would understate what a delete breaks. Unknown is the honest answer, and
+ * {@link mediaUsageHeadline} says the word.
+ *
+ * @docs studio/projects/media
+ */
+
+import { authoredRefTargets } from "./media-paths";
+import { loadUsages, peekUsages, retryUsages, usageHeadline } from "../services/references";
+import type { UsageQuery, UsageState } from "../services/references";
+import type { ReferenceFile, ReferenceHit, ReferencesResult } from "../types";
+
+/**
+ * The queries whose union answers "what uses this media file?".
+ *
+ * One per authored form. An empty list means there is no question to ask (an empty path), which
+ * {@link loadMediaUsages} reports as a failure rather than as "nothing uses it".
+ */
+export function mediaUsageQueries(path: string): UsageQuery[] {
+  return authoredRefTargets(path).map((target) => ({ path: target }));
+}
+
+/** Merge one file's hits into the accumulator, summing counts per `(refType, ref)`. */
+function mergeFile(into: Map<string, ReferenceFile>, file: ReferenceFile): void {
+  const existing = into.get(file.path);
+  if (!existing) {
+    into.set(file.path, { count: file.count, path: file.path, refs: [...file.refs] });
+    return;
+  }
+  for (const hit of file.refs) {
+    const same = existing.refs.find(
+      (candidate: ReferenceHit) => candidate.refType === hit.refType && candidate.ref === hit.ref,
+    );
+    if (same) {
+      same.count += hit.count;
+    } else {
+      existing.refs.push({ ...hit });
+    }
+  }
+  existing.count += file.count;
+}
+
+/**
+ * One result out of several, for the same file asked about under different names.
+ *
+ * The lanes cannot double-count: each asks about a DIFFERENT resolved path, and one authored string
+ * resolves to exactly one of them. Errors are unioned by path so a document that failed to parse in
+ * every lane is reported once, and `path` reports the media file the caller asked about rather than
+ * whichever lane happened to be first.
+ */
+function unionResults(path: string, results: readonly ReferencesResult[]): ReferencesResult {
+  const files = new Map<string, ReferenceFile>();
+  const errors = new Map<string, { path: string; error: string }>();
+  for (const result of results) {
+    for (const file of result.files) {
+      mergeFile(files, file);
+    }
+    for (const error of result.errors) {
+      if (!errors.has(error.path)) {
+        errors.set(error.path, error);
+      }
+    }
+  }
+  const merged = [...files.values()].toSorted((a, b) => a.path.localeCompare(b.path));
+  return {
+    errors: [...errors.values()],
+    files: merged,
+    filesReferencing: merged.length,
+    path,
+    refsTotal: merged.reduce((sum, file) => sum + file.count, 0),
+    tagName: null,
+  };
+}
+
+/**
+ * Reduce the lanes to one state.
+ *
+ * Precedence is strictly least-informative-wins, because every step down is a step away from a
+ * number the caller could act on: unsupported (the host cannot answer at all) beats failed (it
+ * tried and could not) beats pending beats a real union.
+ */
+function combine(path: string, states: readonly UsageState[]): UsageState {
+  if (states.some((state) => state.status === "unsupported")) {
+    return { status: "unsupported" };
+  }
+  const failure = states.find((state) => state.status === "failed");
+  if (failure) {
+    return failure;
+  }
+  if (states.some((state) => state.status === "pending")) {
+    return { status: "pending" };
+  }
+  return {
+    result: unionResults(
+      path,
+      states.map((state) => (state as { result: ReferencesResult }).result),
+    ),
+    status: "ready",
+  };
+}
+
+/**
+ * The answer right now, WITHOUT starting a request — the synchronous read a lit template needs.
+ *
+ * `null` means at least one lane has never been asked, and the caller decides whether this paint is
+ * the one that asks (see {@link loadMediaUsages}).
+ */
+export function peekMediaUsages(path: string): UsageState | null {
+  const queries = mediaUsageQueries(path);
+  if (queries.length === 0) {
+    return null;
+  }
+  const states: UsageState[] = [];
+  for (const query of queries) {
+    const state = peekUsages(query);
+    if (state === null) {
+      return null;
+    }
+    states.push(state);
+  }
+  return combine(path, states);
+}
+
+/**
+ * Ask every lane and union the answers. Never rejects — a failure is a STATE, because the caller
+ * has to render something and "unknown" is the honest something.
+ */
+export async function loadMediaUsages(path: string): Promise<UsageState> {
+  const queries = mediaUsageQueries(path);
+  if (queries.length === 0) {
+    return { message: "no media file to look for", status: "failed" };
+  }
+  return combine(path, await Promise.all(queries.map((query) => loadUsages(query))));
+}
+
+/** Forget every lane's answer and ask again — the Retry behind a failed media count. */
+export async function retryMediaUsages(path: string): Promise<UsageState> {
+  const queries = mediaUsageQueries(path);
+  if (queries.length === 0) {
+    return { message: "no media file to look for", status: "failed" };
+  }
+  return combine(path, await Promise.all(queries.map((query) => retryUsages(query))));
+}
+
+/**
+ * The one line a media surface shows beside a file.
+ *
+ * `null` when the host has no reference index at all — the surface hides the line rather than
+ * printing a zero it cannot stand behind. A cold or in-flight query says it is counting, and a
+ * failed one says **unknown**, which is a different fact from "unused" and has to read like one.
+ */
+export function mediaUsageHeadline(state: UsageState | null): string | null {
+  if (state === null) {
+    return "Counting references…";
+  }
+  switch (state.status) {
+    case "unsupported": {
+      return null;
+    }
+    case "pending": {
+      return "Counting references…";
+    }
+    case "failed": {
+      return "Usage unknown";
+    }
+    default: {
+      return usageHeadline(state.result);
+    }
+  }
+}