@krapwoo/ds-viewer 0.6.2 → 0.6.3

package/README.md

@@ -526,6 +526,11 @@ and adds what only a real render shows:
 It needs `puppeteer` in your project (`npm install --save-dev puppeteer`); ds-viewer doesn't
 install a browser. It takes about two minutes for 50 pages and works with `--json` (progress
 goes to stderr), `--ci` and `doctor.strict`, so CI can run `npx ds-viewer doctor --render --ci`.
+
+It starts its own `dev` server, with `--no-update-endpoint` and its own generated directory
+(`.ds-viewer-render/`, gitignored by `init` alongside `.ds-viewer/`). Nothing it generates touches
+the workspace a running `dev` owns, so you can run it beside a catalog you already have open and
+that catalog is unaffected — including its update page's actions.
 It stops the viewer it started, including on Ctrl-C (exit codes 130, 143 or 129 for SIGINT,
 SIGTERM or SIGHUP). On Windows it stops the viewer with `taskkill`; that path is unit-tested, not
 run on a real Windows machine.

package/dist/cli/dev.js

@@ -6,7 +6,7 @@ import { execFile } from 'node:child_process';
 import { promisify } from 'node:util';
 import { resolveConfig } from "./config.js";
 import { sync } from "./sync.js";
-import { writeWorkspace } from "./workspace.js";
+import { workspacePath, writeWorkspace } from "./workspace.js";
 import { findFreePort } from "./port.js";
 import { globBaseFolder } from "./glob.js";
 import { buildVersionStatus, createVersionController, defaultPreferencesDir, readPersonalAutoCheck, resolveAutoCheck, runUpdateCheck, statusFromCheck, writeUpdateFile, writeVersionFile, } from "./updateCheck.js";
@@ -15,9 +15,10 @@ import { createUpdateEndpoint } from "./endpoint.js";
 import { buildUpdatePlan } from "./updatePlan.js";
 import { lastSummaryLine } from "./doctor.js";
 import { detectPackageManager, installUpgradeCommand, platformCommand } from "./packageManager.js";
+import { DEFAULT_WORKSPACE_DIR, RENDER_WORKSPACE_DIR } from "./types.js";
 export class LocalInstallMissingError extends Error {
 }
-const IGNORED_WATCH_SEGMENTS = new Set(['.ds-viewer', 'node_modules', '.git']);
+const IGNORED_WATCH_SEGMENTS = new Set([DEFAULT_WORKSPACE_DIR, RENDER_WORKSPACE_DIR, 'node_modules', '.git']);
 /** False for a changed path under `.ds-viewer/` (package-owned output — reacting to it would make
  *  `dev`'s own `sync` retrigger itself), `node_modules/`, or `.git/`; true for everything else, so
  *  `dev`'s watcher (below) only re-syncs on a project source change. */
@@ -58,8 +59,13 @@ export function watchTargetFolders(config) {
  *  workspace until `dev` was restarted, because `writeWorkspace` was never called again with the
  *  new value (controller end-to-end finding E1). Returns the freshly-resolved config so `dev` can
  *  keep watching with it. */
-export function reloadWorkspace(projectRoot, updateEndpoint) {
-    const config = resolveConfig(projectRoot);
+export function reloadWorkspace(projectRoot, updateEndpoint, 
+// `resolveConfig` reads the user's file, which never names a workspace directory, so a run that
+// owns a non-default one has to put it back — otherwise a config change moves every generated
+// file into `.ds-viewer`, which is the collision this parameter exists to prevent.
+workspaceDir) {
+    const resolved = resolveConfig(projectRoot);
+    const config = workspaceDir ? { ...resolved, workspaceDir } : resolved;
     sync(config);
     writeWorkspace(config, updateEndpoint);
     return config;
@@ -81,8 +87,8 @@ export async function refreshUpdateFile(config, ownVersion, options = {}) {
             ? statusFromCheck(ownVersion, autoCheck, { result: await injected(ownVersion), reached: true })
             : { current: ownVersion, autoCheck, lastOutcome: 'not-run', update: null }
         : await buildVersionStatus(ownVersion, autoCheck);
-    writeUpdateFile(config.projectRoot, status.update ? { ...status.update, checkedAt: status.lastCheckedAt ?? new Date().toISOString() } : undefined);
-    writeVersionFile(config.projectRoot, status);
+    writeUpdateFile(config.projectRoot, status.update ? { ...status.update, checkedAt: status.lastCheckedAt ?? new Date().toISOString() } : undefined, config.workspaceDir);
+    writeVersionFile(config.projectRoot, status, config.workspaceDir);
     return status;
 }
 // Promisified, not `execFileSync` — install/migrate/doctor each take real seconds, and this now
@@ -246,7 +252,7 @@ export async function performRestart(handoff, deps = {}) {
     try {
         for (const watcher of handoff.watchers)
             watcher.close();
-        handoff.endpointServer.close();
+        handoff.endpointServer?.close();
         killGroup(handoff.child, 'SIGTERM');
         // Errata 7d: race the old child's exit against a 10s timer, then SIGKILL the group — a wedged
         // Expo/Metro process must never block the restart forever.
@@ -299,13 +305,15 @@ export async function performRestart(handoff, deps = {}) {
 export async function dev(initialConfig, devOptions = {}) {
     assertLocalInstall(initialConfig.projectRoot);
     const ownVersion = readOwnVersion(import.meta.dirname);
-    let config = initialConfig;
+    // Carried on the config so every writer (sync, writeWorkspace, the update files) lands in this
+    // run's own directory, and so a config reload cannot silently drop it.
+    let config = devOptions.workspaceDir ? { ...initialConfig, workspaceDir: devOptions.workspaceDir } : initialConfig;
     const version = createVersionController({
         ownVersion,
         projectRoot: initialConfig.projectRoot,
         prefsDir: defaultPreferencesDir(),
         env: process.env,
-        initial: await refreshUpdateFile(initialConfig, ownVersion),
+        initial: await refreshUpdateFile(config, ownVersion),
         getConfig: () => config,
         // **Check now** always asks npm, even with automatic checks off: you asked for this one check.
         // The result lives only in this process; `update.json` and `version.json` are rewritten at
@@ -316,7 +324,7 @@ export async function dev(initialConfig, devOptions = {}) {
     // Restart handoff step 2/4: a status file left by the *previous* `dev` process (right before it
     // exited to restart) is read once, then deleted — a plain refresh afterward shows "idle"/"no
     // update known" instead of replaying a stale success/failure forever.
-    const statusFile = path.join(config.projectRoot, '.ds-viewer', 'update-status.json');
+    const statusFile = workspacePath(config, 'update-status.json');
     let updateStatus = { phase: 'idle' };
     if (existsSync(statusFile)) {
         try {
@@ -390,14 +398,24 @@ export async function dev(initialConfig, devOptions = {}) {
         checkNow: version.checkNow,
         setAutoCheck: version.setAutoCheck,
     };
-    const endpointServer = createUpdateEndpoint(endpointDeps);
-    await new Promise((resolve) => endpointServer.listen(0, '127.0.0.1', resolve));
-    const endpointPort = endpointServer.address().port;
-    // Printed for the same reason the Metro port above is printed: a developer (or Task 20's own
-    // verification) checking the endpoint directly (e.g. with curl) needs its port — the secret
-    // itself is never printed; the endpoint rejects anything that doesn't already have it.
-    console.log(`Update endpoint listening on 127.0.0.1:${endpointPort}`);
-    const updateEndpoint = { baseUrl: `http://127.0.0.1:${endpointPort}`, secret };
+    // A throwaway server (a render check's own `dev`) takes no update actions, and creating an
+    // endpoint would bake its short-lived port into the shared workspace — pointing an already-open
+    // catalog at a port that dies with this process. See `writeWorkspace`.
+    let updateEndpoint;
+    let endpointServer;
+    if (!devOptions.noUpdateEndpoint) {
+        endpointServer = createUpdateEndpoint(endpointDeps);
+        await new Promise((resolve) => endpointServer.listen(0, '127.0.0.1', resolve));
+        const endpointPort = endpointServer.address().port;
+        // Printed for the same reason the Metro port above is printed: a developer (or Task 20's own
+        // verification) checking the endpoint directly (e.g. with curl) needs its port — the secret
+        // itself is never printed; the endpoint rejects anything that doesn't already have it.
+        console.log(`Update endpoint listening on 127.0.0.1:${endpointPort}`);
+        updateEndpoint = { baseUrl: `http://127.0.0.1:${endpointPort}`, secret };
+    }
+    else {
+        console.log('Update endpoint disabled for this run (--no-update-endpoint).');
+    }
     const workspace = writeWorkspace(config, updateEndpoint);
     let debounceTimer;
     const onSourceChange = (_eventType, relativePath) => {
@@ -426,7 +444,7 @@ export async function dev(initialConfig, devOptions = {}) {
         clearTimeout(configDebounceTimer);
         configDebounceTimer = setTimeout(() => {
             try {
-                config = reloadWorkspace(config.projectRoot, updateEndpoint);
+                config = reloadWorkspace(config.projectRoot, updateEndpoint, config.workspaceDir);
                 version.refreshAutoCheck();
             }
             catch (error) {
@@ -451,7 +469,7 @@ export async function dev(initialConfig, devOptions = {}) {
     child.on('exit', (code) => {
         for (const watcher of watchers)
             watcher.close();
-        endpointServer.close();
+        endpointServer?.close();
         process.exitCode = code ?? 0;
     });
     // Node's default SIGTERM/SIGINT/SIGHUP behavior exits this process without touching its
@@ -464,7 +482,7 @@ export async function dev(initialConfig, devOptions = {}) {
         process.on(signal, () => {
             for (const watcher of watchers)
                 watcher.close();
-            endpointServer.close();
+            endpointServer?.close();
             killGroup(child, signal);
             process.exit(0);
         });
@@ -476,7 +494,7 @@ export async function dev(initialConfig, devOptions = {}) {
         console.error(`Unexpected error: ${error instanceof Error ? error.message : String(error)}`);
         for (const watcher of watchers)
             watcher.close();
-        endpointServer.close();
+        endpointServer?.close();
         killGroup(child, 'SIGTERM');
         process.exit(1);
     };

package/dist/cli/endpoint.js

@@ -50,6 +50,17 @@ function sendJson(res, status, body, allowedOrigin) {
     res.writeHead(status, { 'Content-Type': 'application/json', 'Access-Control-Allow-Origin': allowedOrigin });
     res.end(JSON.stringify(body));
 }
+/** For a refusal the page is *allowed* to read: a wrong secret or an unknown route, where the
+ *  Origin check has already passed. Without the allow-origin header the browser blocks the
+ *  response and the page cannot tell "wrong secret" from "server not running" — both arrive as
+ *  the same opaque network failure, which is how a stale secret looked like a dead server.
+ *
+ *  A rejected or absent Origin deliberately gets no CORS headers at all (see the Origin checks
+ *  below): a page from somewhere else is told nothing, not even which origin is allowed. */
+function sendText(res, status, body, allowedOrigin) {
+    res.writeHead(status, { 'Content-Type': 'text/plain', 'Access-Control-Allow-Origin': allowedOrigin });
+    res.end(body);
+}
 /** Design §5 "Local endpoint safeguards", every one of them, in the exact order this plan's own
  *  `spikes/cors-endpoint/` spike proved: Origin (including `OPTIONS`) → secret → route. Does not
  *  call `.listen()` itself — Task 18's `dev.ts` owns the real port (`0` → OS-assigned, `127.0.0.1`
@@ -102,7 +113,7 @@ export function createUpdateEndpoint(deps) {
             return;
         }
         if (!secretMatches(req.headers[DS_VIEWER_SECRET_HEADER], deps.secret)) {
-            res.writeHead(401).end('Missing or wrong secret.');
+            sendText(res, 401, 'Missing or wrong secret.', deps.allowedOrigin);
             return;
         }
         if (req.method === 'POST' && req.url === '/plan') {
@@ -245,6 +256,6 @@ export function createUpdateEndpoint(deps) {
             }
             return;
         }
-        res.writeHead(404).end('Not found.');
+        sendText(res, 404, 'Not found.', deps.allowedOrigin);
     });
 }

package/dist/cli/init.js

@@ -7,6 +7,7 @@ import { detectComponentFolders, detectTokenFiles } from "./detect.js";
 import { ensureAgentsFileSection } from "./agentsFile.js";
 import { ensureGithubAction } from "./githubAction.js";
 import { readOwnVersion } from "./packageVersion.js";
+import { DEFAULT_WORKSPACE_DIR, RENDER_WORKSPACE_DIR } from "./types.js";
 async function promptConfirm(message) {
     // A closed, non-interactive stdin (CI, piped npx) would reject `question` with an AbortError;
     // say how to proceed instead.
@@ -129,11 +130,15 @@ function ensureSharedProjectFiles(projectRoot) {
         written.push(packageJsonPath);
     }
     const gitignorePath = path.join(projectRoot, '.gitignore');
-    const gitignoreEntry = '.ds-viewer/';
+    // Both generated workspaces: the one `dev` owns, and the one `doctor --render`'s own server uses
+    // so it never writes the files `dev` is serving.
+    const gitignoreEntries = [`${DEFAULT_WORKSPACE_DIR}/`, `${RENDER_WORKSPACE_DIR}/`];
     const existingGitignore = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf8') : '';
-    if (!existingGitignore.split('\n').some((line) => line.replace(/\r$/, '') === gitignoreEntry)) {
+    const presentLines = new Set(existingGitignore.split('\n').map((line) => line.replace(/\r$/, '')));
+    const missing = gitignoreEntries.filter((entry) => !presentLines.has(entry));
+    if (missing.length > 0) {
         const separator = existingGitignore === '' || existingGitignore.endsWith('\n') ? '' : '\n';
-        writeFileSync(gitignorePath, `${existingGitignore}${separator}${gitignoreEntry}\n`);
+        writeFileSync(gitignorePath, `${existingGitignore}${separator}${missing.join('\n')}\n`);
         written.push(gitignorePath);
     }
     written.push(...ensureAgentsFileSection(projectRoot));

package/dist/cli/main.js

@@ -7,6 +7,7 @@ import { dev } from "./dev.js";
 import { sync } from "./sync.js";
 import { formatHuman, runDoctor, toDoctorJson, withExtraIssues } from "./doctor.js";
 import { renderCheck } from "./render.js";
+import { RENDER_WORKSPACE_DIR } from "./types.js";
 import { explainPage, formatExplain, parseHeights } from "./explain.js";
 import { readOwnVersion } from "./packageVersion.js";
 import { checkForUpdate, defaultPreferencesDir, readPersonalAutoCheck, resolveAutoCheck } from "./updateCheck.js";
@@ -25,6 +26,10 @@ Commands:
   dev      Sync, then serve the catalog on a local web address and keep it current as files change
            [--port <number>]
            Pin the catalog (and its update endpoint's restart handoff) to this port
+           [--no-update-endpoint]
+           Serve with no local update endpoint, leaving the one a running dev server recorded alone
+           [--workspace-dir <name>]
+           Generate into this directory instead of .ds-viewer, so two servers never share files
   doctor   Check every page for drift and coverage gaps
            --json          print the machine-readable report instead
            --ci            exit 1 when any error was found (never on a warning alone)
@@ -243,7 +248,22 @@ async function main() {
         const portIndex = rest.indexOf('--port');
         const parsedPort = portIndex !== -1 ? Number(rest[portIndex + 1]) : undefined;
         const pinnedPort = parsedPort !== undefined && Number.isInteger(parsedPort) ? parsedPort : undefined;
-        await dev(config, { pinnedPort });
+        // `--no-update-endpoint`: run the catalog without the local update endpoint, and leave the
+        // endpoint an already-running `dev` recorded in the shared workspace alone. `doctor --render`
+        // starts its own server this way.
+        const noUpdateEndpoint = rest.includes('--no-update-endpoint');
+        // `--workspace-dir <name>`: which generated directory this run owns, so a second server (a
+        // render check's own) never writes the files the first one is serving. A bare directory name
+        // only — anything with a path separator, or a parent reference, would let an argument write
+        // outside the project.
+        const dirIndex = rest.indexOf('--workspace-dir');
+        const requestedDir = dirIndex !== -1 ? rest[dirIndex + 1] : undefined;
+        if (requestedDir !== undefined && (requestedDir === '' || requestedDir !== path.basename(requestedDir) || requestedDir.startsWith('.') === false)) {
+            console.error(`--workspace-dir must be a single hidden directory name such as ${RENDER_WORKSPACE_DIR}.`);
+            process.exitCode = 1;
+            return;
+        }
+        await dev(config, { pinnedPort, noUpdateEndpoint, workspaceDir: requestedDir });
         return;
     }
     console.error(`Unknown command "${command}".\n\n${USAGE}`);

package/dist/cli/render.js

@@ -2,9 +2,11 @@
 // only a real render shows (console errors, pages that fail to render, the viewer's own [Catalog]
 // layout warnings). The browser is resolved from the project; ds-viewer never installs one.
 import { spawn, spawnSync } from 'node:child_process';
+import { get as httpGet } from 'node:http';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { RENDER_WORKSPACE_DIR } from "./types.js";
 const OVERFLOW = /is \d+px wide in a \d+px cell/;
 /**
  * Turns one page's console output into doctor findings. Console errors and a missing heading are
@@ -173,10 +175,34 @@ function outputTail() {
 }
 /** Starts the project's own `dev` in its own process group. `onSpawn` receives the child at once,
  *  so a signal during startup can still stop it. */
+/** Polls `http://localhost:<port>/` until it answers, so a caller never navigates to a port Metro
+ *  has not bound yet. Any HTTP reply counts — the page's own content is checked afterwards. */
+async function waitForServer(port, timeoutMs = DEV_START_TIMEOUT_MS) {
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const answered = await new Promise((resolve) => {
+            const request = httpGet({ host: 'localhost', port, path: '/', timeout: 2000 }, () => resolve(true));
+            request.on('error', () => resolve(false));
+            request.on('timeout', () => {
+                request.destroy();
+                resolve(false);
+            });
+        });
+        if (answered)
+            return;
+        if (Date.now() > deadline)
+            throw new Error(`Timed out waiting for the catalog to answer on port ${port}.`);
+        await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+}
 function startDev(projectRoot, onSpawn) {
     const main = path.join(path.dirname(fileURLToPath(import.meta.url)), 'main.js');
     return new Promise((resolve, reject) => {
-        const child = spawn(process.execPath, [main, 'dev'], {
+        // Its own workspace directory and no update endpoint: this server exists to render pages, and
+        // every file it generates would otherwise overwrite the ones an already-running `dev` is
+        // serving — including that developer's endpoint, pointing their open catalog at a port that
+        // dies with this check.
+        const child = spawn(process.execPath, [main, 'dev', '--no-update-endpoint', '--workspace-dir', RENDER_WORKSPACE_DIR], {
             cwd: projectRoot,
             env: { ...process.env, CI: '1', DS_VIEWER_NO_UPDATE_CHECK: '1' },
             detached: process.platform !== 'win32',
@@ -202,7 +228,13 @@ function startDev(projectRoot, onSpawn) {
             if (match && !done) {
                 done = true;
                 clearTimeout(timer);
-                resolve({ child, port: Number(match[1]) });
+                // `dev` prints that line before it spawns Expo, so the port is known well before Metro is
+                // listening on it. Resolving here raced the bundler: the first navigation could land on a
+                // port nothing was bound to yet. Wait for the server to actually answer.
+                const port = Number(match[1]);
+                waitForServer(port)
+                    .then(() => resolve({ child, port }))
+                    .catch((error) => fail(`${error.message} `));
             }
         });
         child.on('exit', (code) => fail(`ds-viewer dev exited early (code ${code}).`));
@@ -272,10 +304,18 @@ export async function renderCheck(projectRoot, options = {}) {
             }
         }
         // Runs in the browser; `document` is typed loosely because the CLI compiles without DOM types.
-        const hrefs = await home.evaluate(() => {
+        const readHrefs = () => home.evaluate(() => {
             const doc = globalThis.document;
             return [...new Set(Array.from(doc.querySelectorAll('a[href^="#"]')).map((a) => a.getAttribute('href') ?? ''))];
         });
+        // The server answers before the bundle has run, and a workspace Metro has never bundled before
+        // (a fresh `.ds-viewer-render`) is slow the first time. Keep asking until the sidebar is there,
+        // rather than reading once and calling an empty page a failed render.
+        let hrefs = await readHrefs();
+        while (hrefs.length === 0 && Date.now() < deadline) {
+            await new Promise((r) => setTimeout(r, 500));
+            hrefs = await readHrefs();
+        }
         await home.close();
         const ids = hrefs.map(idFromHref).filter(Boolean);
         if (ids.length === 0) {

package/dist/cli/sync.js

@@ -4,13 +4,14 @@ import { globBaseFolder, resolveGlob } from "./glob.js";
 import { createComponentReader } from "./props.js";
 import { readTokenModules } from "./tokens.js";
 import { discoverPages, writePageIndex } from "./pageIndex.js";
+import { workspacePath } from "./workspace.js";
 const GENERATED_INDEX = "export { default as components } from './components.json';\nexport { default as tokens } from './tokens.json';\n";
 /** Reads detection, props, and tokens from source, then writes `.ds-viewer/generated/`
  *  (design §3 — "Output and speed": `components.json`, `tokens.json`, and the page import list,
  *  sorted and deterministic). Nothing from the project is executed. `resolveOptions` is test-only
  *  (see this task's Interfaces note) — production callers omit it. */
 export function sync(config, resolveOptions) {
-    const generatedDir = path.join(config.projectRoot, '.ds-viewer', 'generated');
+    const generatedDir = workspacePath(config, 'generated');
     mkdirSync(generatedDir, { recursive: true });
     const excluded = new Set((config.exclude ?? []).flatMap((pattern) => resolveGlob(config.projectRoot, pattern)));
     const componentEntryFiles = config.components.flatMap((pattern) => resolveGlob(config.projectRoot, pattern)).filter((file) => !excluded.has(file));

package/dist/cli/types.js

@@ -1 +1,8 @@
-export {};
+/** `DsViewerConfig` plus where it came from. Every CLI command after config loading works with
+ *  this, not the raw `DsViewerConfig`, so paths are always resolved against the right project. */
+/** The generated Expo workspace's directory name, relative to `projectRoot`. The default is the
+ *  only one a user ever sees; a throwaway server (a render check's own `dev`) uses its own so the
+ *  two never write the same files. */
+export const DEFAULT_WORKSPACE_DIR = '.ds-viewer';
+/** Used by `doctor --render`'s own `dev`. Gitignored next to the default. */
+export const RENDER_WORKSPACE_DIR = '.ds-viewer-render';

package/dist/cli/updateCheck.js

@@ -2,6 +2,7 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { compareVersions, isBreakingUpgrade, parseVersion } from "./semver.js";
+import { DEFAULT_WORKSPACE_DIR } from "./types.js";
 const CACHE_FILE_NAME = 'update-check.json';
 const PACKAGE_NAME = '@krapwoo/ds-viewer';
 const REGISTRY_URL = `https://registry.npmjs.org/${encodeURIComponent(PACKAGE_NAME).replace('%40', '@')}/latest`;
@@ -229,9 +230,10 @@ export function statusFromCheck(currentVersion, autoCheck, outcome) {
         update: toNotice(outcome.result),
     };
 }
-/** `dev` writes this next to `update.json`; the generated entry file imports it. */
-export function writeVersionFile(projectRoot, status) {
-    const file = path.join(projectRoot, '.ds-viewer', 'version.json');
+/** `dev` writes this next to `update.json`; the generated entry file imports it. `workspaceDir`
+ *  is the run's own generated directory — see `workspacePath`. */
+export function writeVersionFile(projectRoot, status, workspaceDir = DEFAULT_WORKSPACE_DIR) {
+    const file = path.join(projectRoot, workspaceDir, 'version.json');
     mkdirSync(path.dirname(file), { recursive: true });
     writeFileSync(file, JSON.stringify(status));
     return file;
@@ -239,8 +241,8 @@ export function writeVersionFile(projectRoot, status) {
 /** Design §5: "`dev` writes the result to `.ds-viewer/update.json`; the viewer reads it." Always
  *  writes something — `null` when there is no result — so the generated entry file (Task 17) can
  *  unconditionally `import updateNotice from './update.json'` without ever hitting a missing file. */
-export function writeUpdateFile(projectRoot, result) {
-    const file = path.join(projectRoot, '.ds-viewer', 'update.json');
+export function writeUpdateFile(projectRoot, result, workspaceDir = DEFAULT_WORKSPACE_DIR) {
+    const file = path.join(projectRoot, workspaceDir, 'update.json');
     mkdirSync(path.dirname(file), { recursive: true });
     writeFileSync(file, JSON.stringify(result ?? null));
     return file;

package/dist/cli/workspace.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { globBaseFolder } from "./glob.js";
+import { DEFAULT_WORKSPACE_DIR } from "./types.js";
 function metroConfigJs(extraWatchFolders) {
     return `const path = require('path');
 const fs = require('fs');
@@ -99,11 +100,23 @@ function configGlobFolders(config) {
 function projectIncludeGlobs(config) {
     return configGlobFolders(config).map((folder) => `../${folder}/**/*`);
 }
+/** This run's generated workspace directory. Every writer goes through here, so a run that owns a
+ *  different directory (a render check's throwaway server) cannot touch another server's files. */
+export function workspacePath(config, ...segments) {
+    return path.join(config.projectRoot, config.workspaceDir ?? DEFAULT_WORKSPACE_DIR, ...segments);
+}
 /** Writes the self-contained Expo web workspace at `.ds-viewer/` (design §2 "The preview
  *  workspace and `npx ds-viewer dev`"). Rewritten freely on every `dev` run — nothing here is
- *  user-owned. */
+ *  user-owned.
+ *
+ *  `updateEndpoint` is the caller's own, inlined into `entry.tsx`. Without one (a render check's
+ *  throwaway server, `--no-update-endpoint`) the catalog is served with no endpoint at all, so it
+ *  makes no calls: the shell polls `/version` from every page, so inlining a *different* server's
+ *  endpoint here would have every page call it from the wrong origin. Two `dev` servers share this
+ *  one directory, so the last writer decides — see the README on running a render check beside an
+ *  open catalog. */
 export function writeWorkspace(config, updateEndpoint) {
-    const workspace = path.join(config.projectRoot, '.ds-viewer');
+    const workspace = workspacePath(config);
     mkdirSync(workspace, { recursive: true });
     writeFileSync(path.join(workspace, 'package.json'), `${JSON.stringify({ name: 'ds-viewer-workspace', private: true, main: 'entry.tsx' }, null, 2)}\n`);
     writeFileSync(path.join(workspace, 'app.json'), `${JSON.stringify({ expo: { name: config.name, slug: 'ds-viewer-workspace', platforms: ['web'] } }, null, 2)}\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krapwoo/ds-viewer",
-  "version": "0.6.2",
+  "version": "0.6.3",
   "license": "MIT",
   "type": "module",
   "description": "A browsable, always-current catalog for an Expo / React Native design system.",