@bendyline/docblocks 2.6.1 → 2.7.0

package/dist/workspace-settings/index.js

@@ -0,0 +1,820 @@
+import {
+  CATALOG_FORMAT_VERSION,
+  CATALOG_GENERATOR,
+  CATALOG_LIMITS,
+  OUTSIDE_IN_FORMAT_IDS,
+  buildCatalogMarkdownDocument,
+  catalogEntryForUnreadable,
+  catalogEntryFromDocument,
+  catalogEntryFromMarkdown,
+  chooseOutsideInMarkdownPath,
+  createWorkspaceCatalog,
+  isGeneratedCatalogHtml,
+  isGeneratedCatalogJson,
+  readCatalogHtmlDigest,
+  relativeCatalogLink,
+  relocateOutsideInLayout,
+  resolveOutsideInLayout,
+  serializeCatalogJson,
+  sha256Hex,
+  sortCatalogEntries,
+  stampCatalogHtml
+} from "../chunk-R2JX5N3F.js";
+import {
+  CATALOG_JSON_CONTENT_MODES,
+  CATALOG_SORT_ORDERS,
+  DEFAULT_CATALOG_HTML_PATH,
+  DEFAULT_CATALOG_JSON_PATH,
+  DEFAULT_CATALOG_TITLE,
+  EMPTY_WORKSPACE_SETTINGS,
+  UnsupportedWorkspaceSettingsVersionError,
+  WORKSPACE_SETTINGS_DIRECTORY,
+  WORKSPACE_SETTINGS_LIMITS,
+  WORKSPACE_SETTINGS_PATH,
+  WORKSPACE_SETTINGS_VERSION,
+  WORKSPACE_THEME_ID_PATTERN,
+  applyWorkspaceSettingsPatch,
+  checkCatalogOutputPath,
+  diffWorkspaceSettings,
+  isDefaultWorkspaceSettings,
+  isEmptyWorkspaceSettingsPatch,
+  parseWorkspaceSettings,
+  parseWorkspaceSettingsPatch,
+  parseWorkspaceSettingsText,
+  resolveCatalogOutputs,
+  resolveFallbackThemeId,
+  resolveWorkspaceDefaultThemeId,
+  resolveWorkspaceVersioningEnabled,
+  serializeWorkspaceSettings,
+  tryApplyWorkspaceSettingsPatch,
+  validateCatalogOutputPath
+} from "../chunk-UK7R3RC7.js";
+import {
+  SQUISQ_RUNTIME_DIRECTORY_NAME,
+  isDiscoverableWorkspaceEntry,
+  isIgnoredWorkspaceEntryName,
+  isMarkdownFileName
+} from "../chunk-YHSFRPBS.js";
+import {
+  decodeUtf8Text
+} from "../chunk-M5ZNQGR5.js";
+import {
+  FsError,
+  WORKSPACE_ROOT,
+  parseWorkspacePath
+} from "../chunk-AYWKIZLD.js";
+
+// src/workspace-settings/schema.ts
+var themeId = {
+  type: "string",
+  pattern: WORKSPACE_THEME_ID_PATTERN.source,
+  description: 'A DocBlocks document theme id, such as "warm-earth".'
+};
+var relativePath = {
+  type: "string",
+  minLength: 1,
+  maxLength: WORKSPACE_SETTINGS_LIMITS.maxPathCharacters
+};
+var WORKSPACE_SETTINGS_JSON_SCHEMA = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  title: "DocBlocks workspace settings",
+  description: "Settings shared by everyone who opens this folder in DocBlocks. Every section is optional.",
+  type: "object",
+  additionalProperties: false,
+  required: ["version"],
+  properties: {
+    $schema: { type: "string", maxLength: WORKSPACE_SETTINGS_LIMITS.maxSchemaCharacters },
+    version: { const: 1, description: "Settings format version." },
+    documents: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        defaultTheme: {
+          ...themeId,
+          description: "Theme for documents whose frontmatter does not name one. A document\u2019s own theme always wins."
+        }
+      }
+    },
+    versionHistory: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        enabled: {
+          type: "boolean",
+          description: "Keep prior revisions for documents in this folder. Omit to use the app default."
+        },
+        keep: {
+          type: "integer",
+          minimum: WORKSPACE_SETTINGS_LIMITS.minKeep,
+          maximum: WORKSPACE_SETTINGS_LIMITS.maxKeep,
+          description: "Revisions kept per document."
+        }
+      }
+    },
+    catalog: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        title: {
+          type: "string",
+          minLength: 1,
+          maxLength: WORKSPACE_SETTINGS_LIMITS.maxTitleCharacters,
+          description: `Catalog heading. Defaults to "${DEFAULT_CATALOG_TITLE}".`
+        },
+        sort: {
+          enum: [...CATALOG_SORT_ORDERS],
+          description: 'Catalog order. Defaults to "title".'
+        },
+        exclude: {
+          type: "array",
+          maxItems: WORKSPACE_SETTINGS_LIMITS.maxExcludes,
+          items: relativePath,
+          description: "Workspace-relative folders or files left out of the catalog."
+        },
+        html: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            enabled: { type: "boolean", description: "Regenerate the catalog page on every save." },
+            path: {
+              ...relativePath,
+              pattern: "\\.html?$",
+              description: `Catalog page path. Defaults to "${DEFAULT_CATALOG_HTML_PATH}".`
+            },
+            theme: { ...themeId, description: "Theme for the catalog page only." }
+          }
+        },
+        json: {
+          type: "object",
+          additionalProperties: false,
+          properties: {
+            enabled: { type: "boolean", description: "Regenerate the catalog data on every save." },
+            path: {
+              ...relativePath,
+              pattern: "\\.json$",
+              description: `Catalog data path. Defaults to "${DEFAULT_CATALOG_JSON_PATH}".`
+            },
+            content: {
+              enum: [...CATALOG_JSON_CONTENT_MODES],
+              description: '"metadata" (default) or "markdown" to include each document\u2019s source.'
+            }
+          }
+        }
+      }
+    }
+  }
+};
+
+// src/workspace-settings/outputs.ts
+var WORKSPACE_OUTPUT_LIMITS = {
+  maxDocuments: 5e3,
+  maxDirectories: 2e4,
+  maxDepth: 32,
+  maxDocumentBytes: 4 * 1024 * 1024,
+  maxTotalBytes: 256 * 1024 * 1024,
+  maxOutputBytes: 32 * 1024 * 1024
+};
+var WorkspaceOutputsLimitError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "WorkspaceOutputsLimitError";
+  }
+};
+function createWorkspaceCatalogCache() {
+  return /* @__PURE__ */ new Map();
+}
+function throwIfAborted(signal) {
+  if (signal?.aborted) {
+    throw new FsError("aborted", "Workspace catalog refresh was cancelled.", {
+      operation: "read",
+      retryable: false
+    });
+  }
+}
+function isNotFound(error) {
+  return error instanceof FsError && (error.code === "not-found" || error.code === "type-mismatch");
+}
+function hasUndiscoverableSegment(path) {
+  return path.split("/").some(
+    (segment) => isIgnoredWorkspaceEntryName(segment) || segment === SQUISQ_RUNTIME_DIRECTORY_NAME
+  );
+}
+function isExcluded(path, exclude) {
+  return exclude.some((prefix) => path === prefix || path.startsWith(`${prefix}/`));
+}
+function isCatalogRelevantPath(path, settings) {
+  const normalized = path.replace(/^\/+/, "");
+  if (!normalized || hasUndiscoverableSegment(normalized)) return false;
+  let resolved;
+  try {
+    resolved = resolveCatalogOutputs(settings);
+  } catch {
+    return false;
+  }
+  if (!resolved) return false;
+  const lower = normalized.toLowerCase();
+  return lower !== resolved.html?.path.toLowerCase() && lower !== resolved.json?.path.toLowerCase();
+}
+function isWorkspaceSettingsPath(path) {
+  const normalized = path.replace(/^\/+/, "");
+  return normalized === WORKSPACE_SETTINGS_DIRECTORY || normalized.startsWith(`${WORKSPACE_SETTINGS_DIRECTORY}/`);
+}
+async function collectCandidates(io, resolved, limits, signal) {
+  const outputPaths = new Set(
+    [resolved.html?.path, resolved.json?.path].filter(Boolean).map((path) => path.toLowerCase())
+  );
+  const exclude = resolved.exclude;
+  const candidates = [];
+  const queue = [{ path: WORKSPACE_ROOT, depth: 0 }];
+  let directories = 0;
+  while (queue.length > 0) {
+    throwIfAborted(signal);
+    const { path, depth } = queue.shift();
+    directories += 1;
+    if (directories > limits.maxDirectories) {
+      throw new WorkspaceOutputsLimitError(
+        `This workspace has more than ${limits.maxDirectories} folders; the catalog was not updated.`
+      );
+    }
+    let entries;
+    try {
+      entries = await io.readDirectory(path);
+    } catch (error) {
+      if (path !== WORKSPACE_ROOT && isNotFound(error)) continue;
+      throw error;
+    }
+    for (const entry of entries) {
+      if (!isDiscoverableWorkspaceEntry(entry.name, entry.kind)) continue;
+      if (isExcluded(entry.path, exclude)) continue;
+      if (entry.kind === "directory") {
+        if (depth + 1 > limits.maxDepth) {
+          throw new WorkspaceOutputsLimitError(
+            `Folders nest deeper than ${limits.maxDepth} levels; the catalog was not updated.`
+          );
+        }
+        queue.push({ path: entry.path, depth: depth + 1 });
+        continue;
+      }
+      if (outputPaths.has(entry.path.toLowerCase())) continue;
+      if (isMarkdownFileName(entry.name)) {
+        candidates.push({ kind: "markdown", entry });
+      } else {
+        const layout = resolveOutsideInLayout(entry.path);
+        if (layout) candidates.push({ kind: "outside-in", entry, layout });
+      }
+      if (candidates.length > limits.maxDocuments) {
+        throw new WorkspaceOutputsLimitError(
+          `This workspace has more than ${limits.maxDocuments} documents; the catalog was not updated.`
+        );
+      }
+    }
+  }
+  return candidates;
+}
+var HTML_TITLE = /<title[^>]*>([\s\S]*?)<\/title>/i;
+var HTML_DESCRIPTION = /<meta\b[^>]*\bname\s*=\s*["']description["'][^>]*\bcontent\s*=\s*["']([^"']*)["']/i;
+function decodeEntities(text) {
+  return text.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;|&apos;/g, "'").replace(/&amp;/g, "&");
+}
+async function resolveReadTarget(io, candidate) {
+  if (candidate.kind === "markdown") {
+    return {
+      source: { path: candidate.entry.path, format: "markdown" },
+      readPath: candidate.entry.path,
+      version: candidate.entry.version,
+      size: candidate.entry.size,
+      mode: "markdown"
+    };
+  }
+  const { layout, entry } = candidate;
+  let companion = [];
+  try {
+    companion = await io.readDirectory(parseWorkspacePath(layout.companionDirectory));
+  } catch (error) {
+    if (!isNotFound(error)) throw error;
+  }
+  const markdownPath = chooseOutsideInMarkdownPath(
+    layout,
+    companion.filter((item) => item.kind === "file").map((item) => item.path)
+  );
+  const markdownEntry = markdownPath ? companion.find((item) => item.path === markdownPath) : void 0;
+  if (markdownEntry) {
+    return {
+      source: { path: entry.path, source: markdownEntry.path, format: layout.format },
+      readPath: markdownEntry.path,
+      version: markdownEntry.version,
+      size: markdownEntry.size,
+      mode: "markdown"
+    };
+  }
+  return {
+    source: { path: entry.path, format: layout.format },
+    readPath: layout.format === "html" ? entry.path : null,
+    version: layout.format === "html" ? entry.version : null,
+    size: entry.size,
+    mode: layout.format === "html" ? "html" : "unreadable"
+  };
+}
+async function collectWorkspaceCatalog(io, resolved, renderer, options = {}) {
+  const limits = { ...WORKSPACE_OUTPUT_LIMITS, ...options.limits };
+  const cache = options.cache;
+  const includeMarkdown = resolved.json?.content === "markdown";
+  const candidates = await collectCandidates(io, resolved, limits, options.signal);
+  const entries = [];
+  const seen = /* @__PURE__ */ new Set();
+  let totalBytes = 0;
+  for (const candidate of candidates) {
+    throwIfAborted(options.signal);
+    const target = await resolveReadTarget(io, candidate);
+    seen.add(target.source.path);
+    if (target.mode === "unreadable" || !target.readPath || target.size !== null && target.size > limits.maxDocumentBytes) {
+      entries.push(catalogEntryForUnreadable(target.source));
+      continue;
+    }
+    const cached = cache?.get(target.source.path);
+    if (cached && cached.readPath === target.readPath && cached.version === target.version && cached.includeMarkdown === includeMarkdown) {
+      if (cached.entry) entries.push(cached.entry);
+      continue;
+    }
+    const read = await io.readFile(parseWorkspacePath(target.readPath));
+    if (!read) continue;
+    let entry;
+    if (read.entry.size > limits.maxDocumentBytes) {
+      entry = catalogEntryForUnreadable(target.source);
+    } else {
+      totalBytes += read.entry.size;
+      if (totalBytes > limits.maxTotalBytes) {
+        throw new WorkspaceOutputsLimitError(
+          `Documents in this workspace exceed ${Math.round(limits.maxTotalBytes / 1024 / 1024)} MiB; the catalog was not updated.`
+        );
+      }
+      const text = new TextDecoder("utf-8").decode(read.data);
+      if (target.mode === "markdown") {
+        entry = await catalogEntryFromMarkdown(target.source, text, { includeMarkdown });
+      } else if (isGeneratedCatalogHtml(text)) {
+        entry = null;
+      } else if (renderer.importHtml) {
+        const head = text.slice(0, 64 * 1024);
+        entry = await catalogEntryFromDocument(target.source, await renderer.importHtml(text), {
+          fallbackTitle: decodeEntities(HTML_TITLE.exec(head)?.[1] ?? ""),
+          description: decodeEntities(HTML_DESCRIPTION.exec(head)?.[1] ?? "")
+        });
+      } else {
+        entry = catalogEntryForUnreadable(target.source);
+      }
+    }
+    cache?.set(target.source.path, {
+      readPath: target.readPath,
+      version: read.entry.version,
+      includeMarkdown,
+      entry
+    });
+    if (entry) entries.push(entry);
+  }
+  if (cache) {
+    for (const key of [...cache.keys()]) if (!seen.has(key)) cache.delete(key);
+  }
+  return createWorkspaceCatalog(resolved.title, entries, resolved.sort);
+}
+function withoutMarkdown(catalog) {
+  if (!catalog.documents.some((entry) => entry.markdown !== void 0)) return catalog;
+  return {
+    ...catalog,
+    documents: catalog.documents.map(({ markdown: _markdown, ...entry }) => entry)
+  };
+}
+function sameBytes(left, right) {
+  if (left.byteLength !== right.byteLength) return false;
+  const view = new Uint8Array(left);
+  for (let index = 0; index < view.length; index += 1) {
+    if (view[index] !== right[index]) return false;
+  }
+  return true;
+}
+async function writeOutput(io, request, limits, options) {
+  const { kind, path } = request;
+  const blocked = (message) => ({
+    kind,
+    path,
+    status: "blocked",
+    message
+  });
+  let existing;
+  try {
+    existing = await io.readFile(path);
+  } catch (error) {
+    if (error instanceof FsError && error.code === "type-mismatch") {
+      return blocked(`${path} is a folder. Choose another catalog path.`);
+    }
+    throw error;
+  }
+  if (existing) {
+    const head = new TextDecoder("utf-8").decode(existing.data.slice(0, 4096));
+    const generated = kind === "html" ? isGeneratedCatalogHtml(head) : isGeneratedCatalogJson(head);
+    if (!generated) {
+      return blocked(
+        `${path} already exists and was not created by DocBlocks. Choose another catalog path or remove that file.`
+      );
+    }
+    if (kind === "html" && !options.force && readCatalogHtmlDigest(head) === request.digest) {
+      return { kind, path, status: "unchanged" };
+    }
+  }
+  if (kind === "html") {
+    const layout = resolveOutsideInLayout(path);
+    if (layout && await io.stat(parseWorkspacePath(layout.companionDirectory))) {
+      return blocked(`${path} is an edited document. Choose another catalog path.`);
+    }
+  }
+  const bytes = new TextEncoder().encode(await request.produce());
+  if (bytes.byteLength > limits.maxOutputBytes) {
+    return blocked(
+      `The catalog would exceed ${Math.round(limits.maxOutputBytes / 1024 / 1024)} MiB and was not written.`
+    );
+  }
+  if (existing && sameBytes(existing.data, bytes)) return { kind, path, status: "unchanged" };
+  if (options.dryRun) return { kind, path, status: "would-write" };
+  await io.writeFile(path, bytes, {
+    mode: existing ? "replace" : "create",
+    createParents: true,
+    expectedVersion: existing ? existing.entry.version : null
+  });
+  return { kind, path, status: "written", ...existing ? {} : { created: true } };
+}
+async function refreshWorkspaceOutputs(io, settings, renderer, options = {}) {
+  const resolved = resolveCatalogOutputs(settings);
+  if (!resolved) return { documentCount: 0, outputs: [] };
+  const limits = { ...WORKSPACE_OUTPUT_LIMITS, ...options.limits };
+  const catalog = await collectWorkspaceCatalog(io, resolved, renderer, options);
+  const metadataCatalog = withoutMarkdown(catalog);
+  const outputs = [];
+  if (resolved.json) {
+    throwIfAborted(options.signal);
+    const content = resolved.json.content;
+    outputs.push(
+      await writeOutput(
+        io,
+        {
+          kind: "json",
+          path: resolved.json.path,
+          produce: async () => serializeCatalogJson(content === "markdown" ? catalog : metadataCatalog)
+        },
+        limits,
+        options
+      )
+    );
+  }
+  if (resolved.html) {
+    throwIfAborted(options.signal);
+    const html = resolved.html;
+    const digest = await sha256Hex(
+      JSON.stringify({
+        marker: 1,
+        path: html.path,
+        themeId: html.themeId ?? null,
+        catalog: serializeCatalogJson(metadataCatalog)
+      })
+    );
+    outputs.push(
+      await writeOutput(
+        io,
+        {
+          kind: "html",
+          path: html.path,
+          digest,
+          produce: async () => stampCatalogHtml(
+            await renderer.renderCatalogHtml(
+              buildCatalogMarkdownDocument(metadataCatalog, html.path),
+              { title: catalog.title, themeId: html.themeId }
+            ),
+            digest
+          )
+        },
+        limits,
+        options
+      )
+    );
+  }
+  return { documentCount: catalog.documents.length, outputs };
+}
+
+// src/workspace-settings/store.ts
+var UNAVAILABLE_WORKSPACE_SETTINGS = Object.freeze({
+  status: "unavailable",
+  settings: null,
+  version: null,
+  message: "Workspace settings need a folder workspace."
+});
+var LOADING_WORKSPACE_SETTINGS = Object.freeze({
+  status: "loading",
+  settings: null,
+  version: null,
+  message: null
+});
+var SETTINGS_PATH = parseWorkspacePath(WORKSPACE_SETTINGS_PATH);
+function isWorkspaceSettingsWritable(state) {
+  return state.status === "missing" || state.status === "ready";
+}
+async function readWorkspaceSettings(provider) {
+  let file;
+  try {
+    file = await provider.readFile(SETTINGS_PATH);
+  } catch (error) {
+    return {
+      status: "error",
+      settings: null,
+      version: null,
+      message: `Couldn't read ${WORKSPACE_SETTINGS_PATH}: ${errorMessage(error)}`
+    };
+  }
+  if (!file) return { status: "missing", settings: null, version: null, message: null };
+  let text;
+  try {
+    text = decodeUtf8Text(file.data, { label: WORKSPACE_SETTINGS_PATH, path: SETTINGS_PATH });
+  } catch (error) {
+    return {
+      status: "invalid",
+      settings: null,
+      version: file.entry.version,
+      message: errorMessage(error)
+    };
+  }
+  const parsed = parseWorkspaceSettingsText(text);
+  if (parsed.status === "ok") {
+    return {
+      status: "ready",
+      settings: parsed.settings,
+      version: file.entry.version,
+      message: null
+    };
+  }
+  return {
+    status: parsed.status,
+    settings: null,
+    version: file.entry.version,
+    message: parsed.message
+  };
+}
+function isConcurrentChange(error) {
+  return error instanceof FsError && (error.code === "conflict" || error.code === "already-exists" || error.code === "not-found");
+}
+async function writeSettings(provider, base, version, patch) {
+  const next = applyWorkspaceSettingsPatch(base, patch);
+  if (version === null && isDefaultWorkspaceSettings(next)) {
+    return { status: "missing", settings: null, version: null, message: null };
+  }
+  const snapshot = await provider.writeFile(
+    SETTINGS_PATH,
+    new TextEncoder().encode(serializeWorkspaceSettings(next)),
+    { mode: version ? "replace" : "create", createParents: true, expectedVersion: version }
+  );
+  return { status: "ready", settings: next, version: snapshot.version, message: null };
+}
+async function saveWorkspaceSettingsPatch(provider, observed, patch) {
+  if (!isWorkspaceSettingsWritable(observed)) {
+    throw new Error(observed.message ?? "These workspace settings cannot be changed.");
+  }
+  try {
+    return await writeSettings(provider, observed.settings, observed.version, patch);
+  } catch (error) {
+    if (!isConcurrentChange(error)) throw error;
+  }
+  const fresh = await readWorkspaceSettings(provider);
+  if (!isWorkspaceSettingsWritable(fresh)) {
+    throw new Error(fresh.message ?? "The workspace settings file changed and cannot be updated.");
+  }
+  return writeSettings(provider, fresh.settings, fresh.version, patch);
+}
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+// src/workspace-settings/scheduler.ts
+var IDLE_WORKSPACE_OUTPUTS_STATUS = Object.freeze({
+  state: "idle",
+  result: null,
+  message: null
+});
+var WORKSPACE_OUTPUTS_DEBOUNCE_MS = 2500;
+var WORKSPACE_OUTPUTS_MAX_WAIT_MS = 2e4;
+function outputsSignature(settings) {
+  try {
+    return JSON.stringify(resolveCatalogOutputs(settings));
+  } catch {
+    return "invalid";
+  }
+}
+function describeFailure(error) {
+  if (error instanceof WorkspaceOutputsLimitError) return error.message;
+  if (error instanceof FsError) return `Couldn't update the catalog: ${error.message}`;
+  return `Couldn't update the catalog: ${error instanceof Error ? error.message : String(error)}`;
+}
+function firstBlocked(result) {
+  return result.outputs.find((output) => output.status === "blocked");
+}
+function createWorkspaceOutputsScheduler(options) {
+  const debounceMs = options.debounceMs ?? WORKSPACE_OUTPUTS_DEBOUNCE_MS;
+  const maxWaitMs = options.maxWaitMs ?? WORKSPACE_OUTPUTS_MAX_WAIT_MS;
+  const cache = createWorkspaceCatalogCache();
+  const listeners = /* @__PURE__ */ new Set();
+  let settings = options.settings;
+  let signature = outputsSignature(settings);
+  let status = IDLE_WORKSPACE_OUTPUTS_STATUS;
+  let debounceTimer = null;
+  let maxWaitTimer = null;
+  let running = null;
+  let controller = null;
+  let dirty = false;
+  let forceNext = false;
+  let disposed = false;
+  const setStatus = (next) => {
+    status = next;
+    for (const listener of [...listeners]) listener();
+  };
+  const clearTimers = () => {
+    if (debounceTimer !== null) clearTimeout(debounceTimer);
+    if (maxWaitTimer !== null) clearTimeout(maxWaitTimer);
+    debounceTimer = null;
+    maxWaitTimer = null;
+  };
+  const enabled = () => resolveCatalogOutputsSafe(settings) !== null;
+  const run = () => {
+    clearTimers();
+    if (disposed || !enabled()) {
+      dirty = false;
+      return Promise.resolve(status);
+    }
+    if (running) {
+      dirty = true;
+      return running;
+    }
+    dirty = false;
+    const force = forceNext;
+    forceNext = false;
+    const runSettings = settings;
+    controller = new AbortController();
+    const signal = controller.signal;
+    setStatus({ ...status, state: "running" });
+    running = (async () => {
+      try {
+        const renderer = typeof options.renderer === "function" ? await options.renderer() : options.renderer;
+        let result;
+        try {
+          result = await refreshWorkspaceOutputs(options.provider, runSettings, renderer, {
+            cache,
+            signal,
+            force
+          });
+        } catch (error) {
+          if (!(error instanceof FsError && error.code === "conflict")) throw error;
+          result = await refreshWorkspaceOutputs(options.provider, runSettings, renderer, {
+            cache,
+            signal,
+            force
+          });
+        }
+        const blocked = firstBlocked(result);
+        return { state: "done", result, message: blocked?.message ?? null };
+      } catch (error) {
+        if (error instanceof FsError && error.code === "aborted") {
+          return status.state === "running" ? { ...status, state: "idle" } : status;
+        }
+        return { state: "error", result: null, message: describeFailure(error) };
+      }
+    })().then((next) => {
+      running = null;
+      controller = null;
+      if (!disposed) {
+        setStatus(next);
+        if (dirty) schedule();
+      }
+      return next;
+    });
+    return running;
+  };
+  const schedule = () => {
+    if (disposed || !enabled()) return;
+    if (status.state !== "running") setStatus({ ...status, state: "pending" });
+    if (debounceTimer !== null) clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => void run(), debounceMs);
+    maxWaitTimer ?? (maxWaitTimer = setTimeout(() => void run(), maxWaitMs));
+  };
+  const scheduler = {
+    workspaceId: options.workspaceId,
+    notify(path) {
+      if (disposed) return;
+      if (path !== void 0 && !isCatalogRelevantPath(path, settings)) return;
+      if (running) {
+        dirty = true;
+        return;
+      }
+      schedule();
+    },
+    flush() {
+      if (debounceTimer !== null || maxWaitTimer !== null) void run();
+    },
+    regenerate(regenerateOptions) {
+      if (regenerateOptions?.force) forceNext = true;
+      if (running) dirty = true;
+      return running ?? run();
+    },
+    updateSettings(next) {
+      settings = next;
+      const nextSignature = outputsSignature(next);
+      if (nextSignature === signature) return;
+      signature = nextSignature;
+      if (!enabled()) {
+        clearTimers();
+        controller?.abort();
+        setStatus(IDLE_WORKSPACE_OUTPUTS_STATUS);
+        return;
+      }
+      scheduler.notify();
+    },
+    getStatus: () => status,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    dispose() {
+      disposed = true;
+      clearTimers();
+      controller?.abort();
+      listeners.clear();
+    }
+  };
+  if (enabled()) scheduler.notify();
+  return scheduler;
+}
+function resolveCatalogOutputsSafe(settings) {
+  try {
+    return resolveCatalogOutputs(settings);
+  } catch {
+    return null;
+  }
+}
+export {
+  CATALOG_FORMAT_VERSION,
+  CATALOG_GENERATOR,
+  CATALOG_JSON_CONTENT_MODES,
+  CATALOG_LIMITS,
+  CATALOG_SORT_ORDERS,
+  DEFAULT_CATALOG_HTML_PATH,
+  DEFAULT_CATALOG_JSON_PATH,
+  DEFAULT_CATALOG_TITLE,
+  EMPTY_WORKSPACE_SETTINGS,
+  IDLE_WORKSPACE_OUTPUTS_STATUS,
+  LOADING_WORKSPACE_SETTINGS,
+  OUTSIDE_IN_FORMAT_IDS,
+  UNAVAILABLE_WORKSPACE_SETTINGS,
+  UnsupportedWorkspaceSettingsVersionError,
+  WORKSPACE_OUTPUTS_DEBOUNCE_MS,
+  WORKSPACE_OUTPUTS_MAX_WAIT_MS,
+  WORKSPACE_OUTPUT_LIMITS,
+  WORKSPACE_SETTINGS_DIRECTORY,
+  WORKSPACE_SETTINGS_JSON_SCHEMA,
+  WORKSPACE_SETTINGS_LIMITS,
+  WORKSPACE_SETTINGS_PATH,
+  WORKSPACE_SETTINGS_VERSION,
+  WORKSPACE_THEME_ID_PATTERN,
+  WorkspaceOutputsLimitError,
+  applyWorkspaceSettingsPatch,
+  buildCatalogMarkdownDocument,
+  catalogEntryForUnreadable,
+  catalogEntryFromDocument,
+  catalogEntryFromMarkdown,
+  checkCatalogOutputPath,
+  chooseOutsideInMarkdownPath,
+  collectWorkspaceCatalog,
+  createWorkspaceCatalog,
+  createWorkspaceCatalogCache,
+  createWorkspaceOutputsScheduler,
+  diffWorkspaceSettings,
+  isCatalogRelevantPath,
+  isDefaultWorkspaceSettings,
+  isEmptyWorkspaceSettingsPatch,
+  isGeneratedCatalogHtml,
+  isGeneratedCatalogJson,
+  isWorkspaceSettingsPath,
+  isWorkspaceSettingsWritable,
+  parseWorkspaceSettings,
+  parseWorkspaceSettingsPatch,
+  parseWorkspaceSettingsText,
+  readCatalogHtmlDigest,
+  readWorkspaceSettings,
+  refreshWorkspaceOutputs,
+  relativeCatalogLink,
+  relocateOutsideInLayout,
+  resolveCatalogOutputs,
+  resolveFallbackThemeId,
+  resolveOutsideInLayout,
+  resolveWorkspaceDefaultThemeId,
+  resolveWorkspaceVersioningEnabled,
+  saveWorkspaceSettingsPatch,
+  serializeCatalogJson,
+  serializeWorkspaceSettings,
+  sortCatalogEntries,
+  stampCatalogHtml,
+  tryApplyWorkspaceSettingsPatch,
+  validateCatalogOutputPath
+};