@krapwoo/ds-viewer 0.6.9 → 0.6.11

package/README.md

@@ -72,6 +72,23 @@ loser then serves a workspace that no longer describes it, which Expo reports as
 with `--workspace-dir .ds-viewer-second`. A lock left behind by a crashed `dev` never blocks the
 next one.
 
+`.ds-viewer/` belongs to the running server, and it repairs it. If something outside the server
+deletes the generated files while it is serving, it says so and writes them back, rather than
+leaving Expo to report an unresolvable `main` field — which names your project's `package.json`, a
+file that is fine and that you never touched:
+
+```
+Something outside this server deleted package.json, app.json, tsconfig.json, metro.config.js,
+entry.tsx from .ds-viewer/. Rewriting them — your project is fine, this is the catalog's own
+generated workspace. If the catalog looks broken, reload the page.
+```
+
+Metro picks the files back up without a restart. The repair is capped at five per run: if
+something is deleting continuously, repairing forever would only hide it, so past the cap the
+server stops and keeps reporting. If you ever see that message, what else was running at the time
+would be useful on [issue #41](https://github.com/krapwoo/design-system-viewer/issues/41) — the
+cause is not yet identified.
+
 `ds-viewer.config.ts` fields: `name`, `logo` (optional — a path to an image asset, shown in the
 sidebar beside the name, or in place of it for a wide wordmark; validated at `sync`/`dev` time
 and bundled into the preview workspace), `components`, `exclude`, `tokens`, `pages`, `groupOrder`, `starterKit` (new-project only —
@@ -502,6 +519,22 @@ Button
     gallery or a whole-page layout.
   - `internal-prop-unknown` — `internalProps` names something that is not a prop of the component,
     so the exemption it was written for is not in effect. Correct the spelling or delete the entry.
+
+  The catalog also warns at render time when a page under-declares the width its examples need.
+  A `PhoneFrame` given a cell narrower than the 375px device scales the whole phone down, and its
+  own body text shrinks with it, so it reports the page, the example and the cell:
+
+      [Catalog] BottomSheet (variants/content-only) is shown at 75% of device size: its cell is
+      283px, narrower than the 375px device. Declare a larger specimenSize so the example keeps
+      the width it is used at.
+
+  `check:catalog` fails on any `[Catalog]` warning, so this is caught in CI. The threshold is 95%,
+  not 100%: a regular cell leaves 370px for a 375px device, and warning about a reduction nobody
+  can see would only train you to ignore the warning. Where the scaling *is* the subject — a page
+  documenting that a narrow cell shrinks the device rather than reflowing it — write
+  `<PhoneFrame intentionalScale>` in that example, so the exemption is visible where the decision
+  was made.
+
   A page's `internalProps: { size: 'why' }` exempts a named prop from `option-not-covered` — for
   plumbing a parent passes (a layout size, an internal surface kind) rather than a value the
   reader picks. It needs a reason per prop, so the exemption is a visible declaration in the page;

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 { clearDevLock, liveDevLock, workspacePath, writeDevLock, writeWorkspace } from "./workspace.js";
+import { clearDevLock, liveDevLock, missingWorkspaceFiles, workspacePath, writeDevLock, 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";
@@ -326,6 +326,42 @@ export async function performRestart(handoff, deps = {}) {
  *  component/token/page changes to re-run `sync`. Metro's own HMR updates the rendered component
  *  when its source changes, but not the generated props table or page list (Task 17 Step 4 relies
  *  on this: editing `Button.tsx` must update its props table, not just hot-reload the component). */
+/** How often a running `dev` checks that its own workspace still exists. Cheap (five `existsSync`
+ *  calls), and slow enough to be invisible: the failure it covers is rare, and noticing within a
+ *  few seconds is soon enough to repair before the next page load. */
+const WORKSPACE_WATCH_INTERVAL_MS = 4000;
+/** How many times one `dev` run will rewrite a workspace that keeps losing files. Past this,
+ *  something is deleting continuously and repairing again would only hide it. */
+const WORKSPACE_REPAIR_LIMIT = 5;
+/** One pass of the workspace integrity check. Returns what it did, so the caller owns the repair
+ *  budget and the tests can drive it without a timer.
+ *
+ *  `updateEndpoint` is the caller's own, passed through unchanged: rebuilding it here from the
+ *  Metro port would point the repaired catalog at the wrong server, silently breaking the update
+ *  panel while telling the developer everything is fine. */
+export function repairWorkspaceIfMissing(deps) {
+    const { config, updateEndpoint, versionStatus, sync, reclaimLock, log = console.warn } = deps;
+    const missing = missingWorkspaceFiles(config);
+    if (missing.length === 0)
+        return { missing, repaired: false };
+    log(`Something outside this server deleted ${missing.join(', ')} from ${config.workspaceDir ?? DEFAULT_WORKSPACE_DIR}/. ` +
+        "Rewriting them — your project is fine, this is the catalog's own generated workspace. " +
+        'If the catalog looks broken, reload the page.');
+    writeWorkspace(config, updateEndpoint);
+    // `entry.tsx` imports both of these, so a rewrite that skips them resolves nothing. Both come
+    // from one status, the way `refreshUpdateFile` writes them, so a repair cannot leave
+    // `version.json` announcing an update that `update.json` denies.
+    const status = versionStatus();
+    if (!existsSync(workspacePath(config, 'update.json'))) {
+        const update = status.update ? { ...status.update, checkedAt: status.lastCheckedAt ?? new Date().toISOString() } : undefined;
+        writeUpdateFile(config.projectRoot, update, config.workspaceDir);
+    }
+    if (!existsSync(workspacePath(config, 'version.json')))
+        writeVersionFile(config.projectRoot, status, config.workspaceDir);
+    reclaimLock();
+    sync(config);
+    return { missing, repaired: true };
+}
 export async function dev(initialConfig, devOptions = {}) {
     assertLocalInstall(initialConfig.projectRoot);
     const ownVersion = readOwnVersion(import.meta.dirname);
@@ -505,8 +541,60 @@ export async function dev(initialConfig, devOptions = {}) {
         shell: process.platform === 'win32',
         detached: true,
     });
+    // This process owns its workspace: nothing else should remove the files that define it. When
+    // they vanish anyway, Metro reports it as `Cannot resolve entry file: the 'main' field defined
+    // in your package.json points to an unresolvable or non-existent path` — which names the
+    // *project's* package.json, a file that is fine and that the developer did not touch. The cause
+    // is still unidentified (issue #41), so this does not pretend to prevent it; it notices, says
+    // plainly what happened, and writes the files back, because `writeWorkspace` is idempotent and
+    // already knows how.
+    //
+    // Capped rather than endless: if something is deleting continuously, rewriting forever would
+    // hide it behind a repair loop. After the cap this stops repairing and keeps saying so, which
+    // leaves the evidence visible.
+    let repairs = 0;
+    const workspaceWatch = setInterval(() => {
+        if (watchersPaused)
+            return; // an update is rewriting the workspace on purpose.
+        if (repairs >= WORKSPACE_REPAIR_LIMIT) {
+            const missing = missingWorkspaceFiles(config);
+            if (missing.length > 0) {
+                console.warn(`The catalog workspace is still losing files (missing ${missing.join(', ')}). Not rewriting them again — ` +
+                    'something outside this server is deleting them. Please report what else was running at https://github.com/krapwoo/design-system-viewer/issues/41');
+            }
+            return;
+        }
+        // Counted as an attempt, not a success: a workspace that cannot be rewritten (a permission
+        // error, a sync failure) would otherwise retry every four seconds forever.
+        if (missingWorkspaceFiles(config).length > 0)
+            repairs += 1;
+        try {
+            // `updateEndpoint` is passed through, never rebuilt: the endpoint listens on its own
+            // ephemeral port, so deriving one from Metro's port here would repair the files and break
+            // the update panel in the same breath.
+            repairWorkspaceIfMissing({
+                config, updateEndpoint, versionStatus: version.getVersionStatus, sync,
+                // Only if no one else took it meanwhile: between losing the lock and this tick, a second
+                // `dev` can legitimately have started and be serving the directory. Overwriting its lock
+                // would leave two servers each believing they own it.
+                reclaimLock: () => {
+                    const other = liveDevLock(config);
+                    if (other && other.pid !== process.pid) {
+                        console.warn(`Not reclaiming ${config.workspaceDir ?? DEFAULT_WORKSPACE_DIR}/: pid ${other.pid} owns it now.`);
+                        return;
+                    }
+                    writeDevLock(config, { pid: process.pid, port });
+                },
+            });
+        }
+        catch (error) {
+            console.warn(`Could not rewrite the workspace: ${error.message}`);
+        }
+    }, WORKSPACE_WATCH_INTERVAL_MS);
+    workspaceWatch.unref?.();
     child.on('error', (error) => console.warn(`Could not start Expo: ${error.message}`));
     child.on('exit', (code) => {
+        clearInterval(workspaceWatch);
         for (const watcher of watchers)
             watcher.close();
         endpointServer?.close();

package/dist/cli/explain.js

@@ -70,7 +70,7 @@ function toSectionDef(page) {
         hide: (page.hideVariants || page.hideStates) ? { variants: page.hideVariants, states: page.hideStates } : undefined,
     };
 }
-function explainBlock(block) {
+function explainBlock(block, availableWidth) {
     if (block.kind === 'grid') {
         const rows = axisItems(block.comparison.rows).length;
         const columns = axisItems(block.comparison.columns).length;
@@ -82,10 +82,10 @@ function explainBlock(block) {
         };
     }
     if (block.kind === 'list') {
-        const geometry = listGeometry(block.items.length, MATRIX_LAYOUT.laptopContentWidth, block.size, block.maxColumns);
+        const geometry = listGeometry(block.items.length, availableWidth, block.size, block.maxColumns);
         return {
             kind: 'list', title: block.title,
-            reason: `${block.items.length} items (${block.size}) → ${geometry.columns} columns × ${geometry.rows} row${geometry.rows === 1 ? '' : 's'}` +
+            reason: `${block.items.length} items (${block.size}) → ${geometry.columns} column${geometry.columns === 1 ? '' : 's'} × ${geometry.rows} row${geometry.rows === 1 ? '' : 's'}` +
                 (geometry.fillers > 0 ? ` (${geometry.fillers} filler${geometry.fillers === 1 ? '' : 's'})` : '') + '.' +
                 surfaceOverrideNote(block.items) + alignOverrideNote(block.items),
         };
@@ -149,29 +149,40 @@ export function explainPage(config, pageId, options = {}) {
         return { pageId, notCheckable: true, blocks: [] };
     const def = toSectionDef(page);
     const blocks = presentationBlocks(def, { defaultPreviewWidths: [402] });
-    const explained = blocks.map(explainBlock);
+    // Two blocks placed side by side get half the row each, which changes how many columns fit.
+    // Reporting the full-width counts for a page the viewer will halve states the wrong geometry as
+    // fact, so the width every block is measured at follows the placement decision.
+    const full = MATRIX_LAYOUT.laptopContentWidth;
+    const half = Math.floor((full - CATALOG_LAYOUT.blockGap) / 2);
     let placement;
+    let blockWidth = full;
     if (blocks.length === 2) {
         if (options.heights) {
             const [firstHeight, secondHeight] = options.heights;
             const decision = choosePlacement({
-                available: MATRIX_LAYOUT.laptopContentWidth,
+                available: full,
                 gap: CATALOG_LAYOUT.blockGap,
                 first: toPlacementBlock(blocks[0], firstHeight),
                 second: toPlacementBlock(blocks[1], secondHeight),
             });
+            if (decision === 'side')
+                blockWidth = half;
             placement = {
                 decision,
-                reason: `With heights ${firstHeight}px/${secondHeight}px on a 1280px laptop (${MATRIX_LAYOUT.laptopContentWidth}px content width): ${decision}.`,
+                reason: `With heights ${firstHeight}px/${secondHeight}px on a 1280px laptop (${full}px content width): ${decision}` +
+                    (decision === 'side' ? `, so each block gets ${half}px.` : `, so each block gets the full ${full}px.`),
             };
         }
         else {
             placement = {
                 decision: 'decided-in-viewer',
-                reason: "Side-by-side placement depends on each block's measured height — decided in the viewer at runtime. Pass --heights <first>,<second> to check it here.",
+                reason: "Side-by-side placement depends on each block's measured height — decided in the viewer at runtime. " +
+                    `The counts above are for the full ${full}px row; side by side each block gets ${half}px instead, which can fit fewer columns. ` +
+                    'Pass --heights <first>,<second> to resolve it here.',
             };
         }
     }
+    const explained = blocks.map((block) => explainBlock(block, blockWidth));
     return { pageId, blocks: explained, placement, intentionalStaticPreviewReason: page.intentionalStaticPreviewReason };
 }
 export function formatExplain(result) {

package/dist/cli/workspace.js

@@ -151,6 +151,18 @@ export function liveDevLock(config, ownPid = process.pid) {
         return undefined;
     return lock;
 }
+/** The files `writeWorkspace` always writes: the ones that define the workspace to Expo and Metro.
+ *  `babel.config.js` is conditional and the update files are written separately, so neither counts
+ *  as missing here. */
+export const WORKSPACE_DEFINING_FILES = ['package.json', 'app.json', 'tsconfig.json', 'metro.config.js', 'entry.tsx'];
+/** Which of those a workspace has lost. A running `dev` owns these files and nothing else should
+ *  remove them, so a non-empty answer means something outside this process deleted them — see
+ *  issue #41, where the cause is still unidentified. Reported rather than diagnosed: the point is
+ *  that the server can say what happened instead of leaving Expo to blame the project's own
+ *  `package.json` with `Cannot resolve entry file`. */
+export function missingWorkspaceFiles(config) {
+    return WORKSPACE_DEFINING_FILES.filter((name) => !existsSync(workspacePath(config, name)));
+}
 /** 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.
@@ -158,9 +170,9 @@ export function liveDevLock(config, ownPid = process.pid) {
  *  `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. */
+ *  endpoint here would have every page call it from the wrong origin. Each `dev` owns its own
+ *  workspace directory (`dev-lock.json`), so a render check beside an open catalog writes to
+ *  `.ds-viewer-render/` rather than this one — see the README. */
 export function writeWorkspace(config, updateEndpoint) {
     const workspace = workspacePath(config);
     mkdirSync(workspace, { recursive: true });

package/native/catalog/PhoneFrame.tsx

@@ -1,7 +1,7 @@
-import React, { useState } from 'react';
+import React, { useState, useRef } from 'react';
 import { Platform, StyleSheet, Text, View, type LayoutChangeEvent } from 'react-native';
 import { CATALOG_COLOR, CATALOG_RADIUS, CATALOG_TYPE } from './tokens';
-import { DEVICE_FRAME, deviceFrameScale } from './deviceFrame';
+import { DEVICE_FRAME, DEVICE_SCALE_WARN_BELOW, deviceFrameScale } from './deviceFrame';
 import { resolveOverlayViewport } from './overlayViewport';
 import { useSpecimenAddress } from './SpecimenAddress';
 
@@ -27,7 +27,16 @@ function isWeb(): boolean {
  * Purely a documentation device: a real app screen never frames itself, so this lives in the
  * catalog framework rather than in an app's component library.
  */
-export function PhoneFrame({ children }: { children: React.ReactNode }) {
+export function PhoneFrame({
+  children,
+  intentionalScale = false,
+}: {
+  children: React.ReactNode;
+  /** This example is *about* the scaling — a page demonstrating that a narrow cell shrinks the
+   *  device rather than reflowing it. Declared here, in the example itself, so the exemption is
+   *  visible where the decision was made instead of hidden in config. */
+  intentionalScale?: boolean;
+}) {
   const address = useSpecimenAddress();
   const [available, setAvailable] = useState(0);
   const [status, setStatus] = useState<'loading' | 'ready' | 'unavailable'>('loading');
@@ -36,6 +45,23 @@ export function PhoneFrame({ children }: { children: React.ReactNode }) {
     if (width > 0 && width !== available) setAvailable(width);
   };
   const scale = deviceFrameScale(available);
+  // A scaled device is a page that under-declared its width: the cell it was given is narrower
+  // than the phone, so the whole viewport shrinks and the example's own text shrinks with it,
+  // which is not the size anyone reads the component at. The scale is already computed, so this
+  // needs no measurement of its own. Guarded to once per transition, like TokenSections' own
+  // degradation warning; `check:catalog` fails on any [Catalog] warning, so this blocks CI.
+  const warnedScale = useRef<string | undefined>(undefined);
+  if (!intentionalScale && available > 0 && scale < DEVICE_SCALE_WARN_BELOW && (globalThis as { __DEV__?: boolean }).__DEV__) {
+    const key = `${available}`;
+    if (warnedScale.current !== key) {
+      warnedScale.current = key;
+      const where = address ? `${address.pageId} (${address.slot}/${address.itemKey})` : 'a PhoneFrame';
+      console.warn(
+        `[Catalog] ${where} is shown at ${Math.round(scale * 100)}% of device size: its cell is ${available}px, ` +
+          `narrower than the ${DEVICE_FRAME.width}px device. Declare a larger specimenSize so the example keeps the width it is used at.`,
+      );
+    }
+  }
   // Until the cell is measured, fit it at the device's proportions rather than drawing at full size
   // for a frame (which would briefly overflow a cell narrower than the device).
   const box = available > 0

package/native/catalog/deviceFrame.ts

@@ -12,3 +12,12 @@ export function deviceFrameScale(availableWidth: number): number {
   if (!(availableWidth > 0)) return 1;
   return Math.min(1, availableWidth / DEVICE_FRAME.width);
 }
+
+/** Below this, a device is scaled enough that its own text is no longer the size a reader sees it
+ *  at, and the page should declare a wider specimen instead.
+ *
+ *  Not exactly 1. A regular cell leaves 370px for a 375px device — a 1.3% reduction nobody can
+ *  see, and warning about it would train authors to ignore the warning. The cases worth a page's
+ *  attention are the ones that shrink a phone by a tenth or more: a 283px cell renders the device
+ *  at 75%, which is the difference between readable body text and not. */
+export const DEVICE_SCALE_WARN_BELOW = 0.95;

package/package.json

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

package/starter-kit/components/BottomSheet/BottomSheet.catalog.tsx

@@ -65,6 +65,10 @@ const dock = (close: () => void) => (
 export default defineCatalogPage({
   component: 'BottomSheet',
   group: 'Components',
+  // Every example is a phone. At the default size two blocks share the row and each cell falls to
+  // 270px, which squeezes the frame until the sheet's own text is barely readable — 'wide' keeps a
+  // 402px minimum, the width the sheet is actually used at.
+  specimenSize: 'wide',
   composedOf: [
     { component: 'TopNav', role: "The header slot, typically a TopNav with a close or back action.", relationship: 'slot' },
     { component: 'Dock', role: "The footer slot, typically a Dock with the sheet's primary actions; a Dock footer gets its shadow once the content scrolls.", relationship: 'slot' },

package/starter-kit/components/Dialog/Dialog.catalog.tsx

@@ -33,6 +33,9 @@ function Demo({ title, body, actions }: { title: string; body?: string; actions:
 export default defineCatalogPage({
   component: 'Dialog',
   group: 'Components',
+  // Every example is a phone. The default size left 283px for a 375px device, rendering it at 75%
+  // — small enough that the dialog's own body text stopped being the size a reader sees.
+  specimenSize: 'wide',
   composedOf: [
     { component: 'ButtonGroup', role: "Lays out the dialog's actions; a dialog's own children decide this, not Dialog.", relationship: 'related' },
   ],