fix(web): avoid missing design-system preview assets (#5381)

Co-authored-by: lefarcen <935902669@qq.com>

Author: open-design-crew[bot]

apps/daemon/src/design-systems/index.ts

@@ -90,6 +90,7 @@ export type DesignSystemStaticFileDetail = {
 
 export type DesignSystemPackageInfo = {
   manifest?: DesignSystemProjectManifest;
+  availableFiles?: string[];
   sourceEvidence?: {
     scannedFileCount?: number;
     tokenCount?: number;
@@ -404,12 +405,49 @@ export async function readDesignSystemPackageInfo(
   if (manifest === null) return null;
 
   const sourceEvidence = await readDesignSystemSourceEvidence(brandRoot, manifest);
+  const availableFiles = await listAvailableDesignSystemPackageFiles(brandRoot, manifest);
   return {
     manifest,
+    ...(availableFiles.length > 0 ? { availableFiles } : {}),
     ...(sourceEvidence ? { sourceEvidence } : {}),
   };
 }
 
+async function listAvailableDesignSystemPackageFiles(
+  brandRoot: string,
+  manifest: DesignSystemProjectManifest,
+): Promise<string[]> {
+  const candidates = new Set<string>(DESIGN_SYSTEM_STATIC_SYSTEM_FILES);
+  const add = (filePath: string | undefined): void => {
+    const cleanPath = typeof filePath === 'string' ? sanitizeRelativeFilePath(filePath) : null;
+    if (cleanPath) candidates.add(cleanPath);
+  };
+
+  add(manifest.files.design);
+  add(manifest.files.tokens);
+  add(manifest.files.components);
+  add(manifest.files.designTokens);
+  add(manifest.files.tailwind);
+  add(manifest.usage);
+  add(manifest.componentsManifest);
+  for (const page of manifest.preview?.pages ?? []) add(page.path);
+  for (const font of manifest.fonts ?? []) add(font.file);
+
+  const out: string[] = [];
+  const resolvedRoot = path.resolve(brandRoot);
+  for (const relativePath of Array.from(candidates).sort()) {
+    const filePath = path.resolve(brandRoot, relativePath);
+    if (filePath !== resolvedRoot && !filePath.startsWith(`${resolvedRoot}${path.sep}`)) continue;
+    try {
+      const stats = await stat(filePath);
+      if (stats.isFile()) out.push(relativePath);
+    } catch (err) {
+      if (!isAbsenceError(err)) throw err;
+    }
+  }
+  return out;
+}
+
 /**
  * Structured (compiled) form of a brand's design system. Optional sibling
  * files alongside DESIGN.md that, when present, give agents a

apps/daemon/tests/design-systems/import.test.ts

@@ -232,6 +232,14 @@ describe('importLocalDesignSystemProject', () => {
 
     const packageInfo = await readDesignSystemPackageInfo(userDesignSystemsRoot, 'kami-app');
     expect(packageInfo?.manifest?.sourceFiles?.report).toBe('source/token-contract.report.json');
+    expect(packageInfo?.availableFiles).toEqual(
+      expect.arrayContaining([
+        'components.html',
+        'preview/app.html',
+        'preview/colors.html',
+      ]),
+    );
+    expect(packageInfo?.availableFiles).not.toContain('system/kit.html');
     expect(packageInfo?.sourceEvidence?.tokenContract).toMatchObject({
       contract: 'TOKEN_SCHEMA',
       selfCheckOk: true,

apps/web/src/components/DesignKitView.tsx

@@ -1583,7 +1583,7 @@ function DesignKitViewInner({
                       </button>
                     ) : null}
                   </div>
-                  <span className={styles.dsCap}>system/kit.html</span>
+                  <span className={styles.dsCap}>{kit.system.kitLabel ?? 'system/kit.html'}</span>
                 </div>
                 <iframe
                   key={dsKitUrl}

apps/web/src/runtime/design-kit.ts

@@ -88,6 +88,7 @@ export interface KitSystem {
   kitDarkUrl?: string;
   tokensUrl?: string;
   indexUrl?: string;
+  kitLabel?: string;
 }
 
 export interface KitAsset {
@@ -134,6 +135,72 @@ const ASSET_TILES: { kind: string; label: string; file: string }[] = [
   { kind: 'form', label: 'Form page', file: 'system/artifacts/form.html' },
 ];
 
+function hasAvailablePackageFile(
+  packageInfo: DesignSystemPackageInfo | undefined,
+  filePath: string | undefined,
+): filePath is string {
+  if (!filePath) return false;
+  const availableFiles = packageInfo?.availableFiles;
+  return Array.isArray(availableFiles) ? availableFiles.includes(filePath) : true;
+}
+
+function firstAvailablePackageFile(
+  packageInfo: DesignSystemPackageInfo | undefined,
+  files: Array<string | undefined>,
+): string | null {
+  return files.find((filePath) => hasAvailablePackageFile(packageInfo, filePath)) ?? null;
+}
+
+function previewPageLabel(pathName: string, title: string | undefined, role: string | undefined): string {
+  const explicit = title?.trim() || role?.trim();
+  if (explicit) return explicit;
+  const base = pathName.split('/').pop()?.replace(/\.[^.]+$/, '') ?? pathName;
+  return base
+    .split(/[-_]+/)
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ') || 'Preview';
+}
+
+type PackagePreviewPageInput = {
+  path?: string;
+  role?: string;
+  title?: string;
+};
+type PackagePreviewPage = PackagePreviewPageInput & { path: string };
+
+function isAvailablePreviewPage(
+  packageInfo: DesignSystemPackageInfo,
+  page: PackagePreviewPageInput,
+): page is PackagePreviewPage {
+  return typeof page.path === 'string' && hasAvailablePackageFile(packageInfo, page.path);
+}
+
+function packageAssetTiles(
+  packageInfo: DesignSystemPackageInfo | undefined,
+  staticUrl: (rel: string) => string,
+): KitAsset[] | undefined {
+  if (!packageInfo) return undefined;
+  const artifactTiles = ASSET_TILES
+    .filter((a) => hasAvailablePackageFile(packageInfo, a.file))
+    .map((a) => ({
+      kind: a.kind,
+      label: a.label,
+      url: staticUrl(a.file),
+    }));
+  if (artifactTiles.length > 0) return artifactTiles;
+
+  const previewPages = packageInfo.manifest?.preview?.pages ?? [];
+  const previewTiles = previewPages
+    .filter((page): page is PackagePreviewPage => isAvailablePreviewPage(packageInfo, page))
+    .map((page) => ({
+      kind: page.role?.trim() || page.path,
+      label: previewPageLabel(page.path, page.title, page.role),
+      url: staticUrl(page.path),
+    }));
+  return previewTiles.length > 0 ? previewTiles : undefined;
+}
+
 function fontList(typography: DesignKit['typography']): KitFont[] {
   return [typography.display, typography.body, typography.mono].filter(
     (f): f is KitFont => Boolean(f),
@@ -453,6 +520,25 @@ export function parsedToKit(parsed: ParsedDesignMd, opts: ParsedKitOptions): Des
   const staticUrl = !opts.editable && opts.designSystemId && opts.packageInfo?.manifest
     ? (rel: string): string => designSystemStaticUrl(opts.designSystemId!, rel)
     : null;
+  const manifestFiles = opts.packageInfo?.manifest?.files;
+  const kitPath = staticUrl
+    ? firstAvailablePackageFile(opts.packageInfo, [
+        'system/kit.html',
+        manifestFiles?.components ?? 'components.html',
+      ])
+    : null;
+  const kitDarkPath = staticUrl
+    ? firstAvailablePackageFile(opts.packageInfo, ['system/kit.dark.html'])
+    : null;
+  const tokensPath = staticUrl
+    ? firstAvailablePackageFile(opts.packageInfo, [
+        'system/tokens.default.json',
+        manifestFiles?.designTokens,
+      ])
+    : null;
+  const indexPath = staticUrl
+    ? firstAvailablePackageFile(opts.packageInfo, ['system/index.html'])
+    : null;
 
   return {
     designSystemId: opts.designSystemId,
@@ -471,17 +557,16 @@ export function parsedToKit(parsed: ParsedDesignMd, opts: ParsedKitOptions): Des
     voice: hasVoice(parsed.voice) ? parsed.voice : undefined,
     imagery: hasImagery(imagery) ? imagery : undefined,
     layout: hasLayout(layout) ? layout : undefined,
-    system: staticUrl
+    system: staticUrl && kitPath
       ? {
-          kitUrl: staticUrl('system/kit.html'),
-          kitDarkUrl: staticUrl('system/kit.dark.html'),
-          tokensUrl: staticUrl('system/tokens.default.json'),
-          indexUrl: staticUrl('system/index.html'),
+          kitUrl: staticUrl(kitPath),
+          ...(kitDarkPath ? { kitDarkUrl: staticUrl(kitDarkPath) } : {}),
+          ...(tokensPath ? { tokensUrl: staticUrl(tokensPath) } : {}),
+          ...(indexPath ? { indexUrl: staticUrl(indexPath) } : {}),
+          kitLabel: kitPath,
         }
       : undefined,
-    assets: staticUrl
-      ? ASSET_TILES.map((a) => ({ kind: a.kind, label: a.label, url: staticUrl(a.file) }))
-      : undefined,
+    assets: staticUrl ? packageAssetTiles(opts.packageInfo, staticUrl) : undefined,
     showcaseHtml: opts.showcaseHtml ?? null,
   };
 }

apps/web/tests/runtime/design-kit.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it } from 'vitest';
+
+import { parseDesignMd } from '../../src/runtime/design-md-parse';
+import { parsedToKit } from '../../src/runtime/design-kit';
+
+describe('parsedToKit package static assets', () => {
+  it('falls back to declared components and omits missing artifacts when packaged system files are absent', () => {
+    const kit = parsedToKit(parseDesignMd('# Tom Modern Design'), {
+      designSystemId: 'tom-modern',
+      editable: false,
+      packageInfo: {
+        availableFiles: [
+          'DESIGN.md',
+          'tokens.css',
+          'components.html',
+        ],
+        manifest: {
+          schemaVersion: 'od-design-system-project/v1',
+          id: 'tom-modern',
+          name: 'Tom Modern Design',
+          category: 'Starter',
+          files: {
+            design: 'DESIGN.md',
+            tokens: 'tokens.css',
+            components: 'components.html',
+          },
+        },
+      },
+    });
+
+    expect(kit.system).toMatchObject({
+      kitUrl: '/api/design-systems/tom-modern/static?path=components.html',
+      kitLabel: 'components.html',
+    });
+    expect(kit.system?.kitDarkUrl).toBeUndefined();
+    expect(kit.assets).toBeUndefined();
+  });
+
+  it('keeps generated system kit and artifact URLs when the package includes them', () => {
+    const kit = parsedToKit(parseDesignMd('# Bento'), {
+      designSystemId: 'bento',
+      editable: false,
+      packageInfo: {
+        availableFiles: [
+          'system/kit.html',
+          'system/kit.dark.html',
+          'system/artifacts/landing.html',
+        ],
+        manifest: {
+          schemaVersion: 'od-design-system-project/v1',
+          id: 'bento',
+          name: 'Bento',
+          category: 'Layout',
+          files: {
+            design: 'DESIGN.md',
+            tokens: 'tokens.css',
+            components: 'components.html',
+          },
+        },
+      },
+    });
+
+    expect(kit.system).toMatchObject({
+      kitUrl: '/api/design-systems/bento/static?path=system%2Fkit.html',
+      kitDarkUrl: '/api/design-systems/bento/static?path=system%2Fkit.dark.html',
+      kitLabel: 'system/kit.html',
+    });
+    expect(kit.assets).toEqual([
+      {
+        kind: 'landing',
+        label: 'Landing page',
+        url: '/api/design-systems/bento/static?path=system%2Fartifacts%2Flanding.html',
+      },
+    ]);
+  });
+});

packages/contracts/src/api/registry.ts

@@ -332,6 +332,8 @@ export interface DesignSystemPackageInfo {
     };
     assetsDir?: string;
   };
+  /** Package-relative files the daemon confirmed exist and can be served via /static. */
+  availableFiles?: string[];
   sourceEvidence?: {
     scannedFileCount?: number;
     tokenCount?: number;