handoff-app 1.2.2-7 → 2.0.0-0

package/src/store/source-files.ts

@@ -0,0 +1,155 @@
+/**
+ * First-class "related source files for an entity" accessor for the workspace store.
+ *
+ * Gathers an entity's declaration plus every `entries`-referenced source file for checkout and
+ * publish. This centralizes that logic so the store, and later transfer, share one definition of
+ * "what travels with an entity".
+ */
+
+import fs from 'fs-extra';
+import path from 'path';
+import { resolveComponentDeclaration } from '../config/runtime';
+import type { ComponentListObject, PatternListObject } from '../transformers/preview/types';
+import { normalizePathForCompare } from '../utils/path';
+import type { RegistryTextFileResource, TextFileKind, TextFileResource } from './types';
+
+/** A normalized record carrying a source directory `path` and resolved absolute `entries`. */
+type SourcedRecord = (ComponentListObject | PatternListObject) & {
+  entries?: Record<string, string | undefined>;
+};
+
+/** Maps a component/pattern `entries` key to the source-file kind it contributes. */
+const ENTRY_KIND_BY_KEY: Record<string, TextFileKind> = {
+  js: 'script',
+  scss: 'style',
+  component: 'component',
+  story: 'story',
+  schema: 'schema',
+  template: 'template',
+  templates: 'template',
+};
+
+/** Source-text content types keyed by file extension (lowercase, no dot). */
+const SOURCE_CONTENT_TYPE_BY_EXT: Record<string, string> = {
+  ts: 'text/typescript; charset=utf-8',
+  tsx: 'text/typescript; charset=utf-8',
+  js: 'application/javascript; charset=utf-8',
+  jsx: 'application/javascript; charset=utf-8',
+  cjs: 'application/javascript; charset=utf-8',
+  mjs: 'application/javascript; charset=utf-8',
+  json: 'application/json; charset=utf-8',
+  css: 'text/css; charset=utf-8',
+  scss: 'text/x-scss; charset=utf-8',
+  sass: 'text/x-sass; charset=utf-8',
+  hbs: 'text/x-handlebars-template; charset=utf-8',
+  md: 'text/markdown; charset=utf-8',
+  html: 'text/html; charset=utf-8',
+};
+
+export const sourceContentTypeForPath = (filePath: string): string => {
+  const ext = path.extname(filePath).slice(1).toLowerCase();
+  return SOURCE_CONTENT_TYPE_BY_EXT[ext] ?? 'text/plain; charset=utf-8';
+};
+
+/**
+ * Read a single text source file into a {@link TextFileResource}, or `null` when it is missing or
+ * unreadable. `relativeTo` is the entity source directory used to derive the registry-safe path.
+ */
+const readTextFile = (
+  absolutePath: string,
+  kind: TextFileKind,
+  relativeTo: string
+): TextFileResource | null => {
+  try {
+    if (!fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isFile()) {
+      return null;
+    }
+    const content = fs.readFileSync(absolutePath, 'utf8');
+    const relative = path.relative(relativeTo, absolutePath).split(path.sep).join('/');
+    return {
+      path: relative || path.basename(absolutePath),
+      absolutePath,
+      kind,
+      content,
+      contentType: sourceContentTypeForPath(absolutePath),
+    };
+  } catch {
+    return null;
+  }
+};
+
+/** Expand a `templates` directory entry into its contained template files. */
+const expandTemplatesDir = (dirPath: string): string[] => {
+  try {
+    if (!fs.existsSync(dirPath) || !fs.statSync(dirPath).isDirectory()) {
+      return [];
+    }
+    return fs
+      .readdirSync(dirPath, { withFileTypes: true })
+      .filter((entry) => entry.isFile())
+      .map((entry) => path.join(dirPath, entry.name));
+  } catch {
+    return [];
+  }
+};
+
+/**
+ * Locate the entity's declaration file within its source directory and read it as a
+ * `kind: 'declaration'` resource. Returns `null` when no declaration can be found/read.
+ */
+const readDeclarationFile = (sourceDir: string): TextFileResource | null => {
+  const declaration = resolveComponentDeclaration(sourceDir, path.basename(sourceDir));
+  if (!declaration) return null;
+  const absolutePath = path.resolve(sourceDir, declaration.fileName);
+  return readTextFile(absolutePath, 'declaration', sourceDir);
+};
+
+/**
+ * Gather an entity's declaration plus every `entries`-referenced source file. Files are deduped by
+ * normalized absolute path (entries duplicate `template`/`component`/`story` after normalization),
+ * and a `templates` directory entry is expanded into its files. Declaration always sorts first.
+ */
+export const getRelatedSourceFilesForRecord = (record: SourcedRecord): TextFileResource[] => {
+  const sourceDir = record.path;
+  if (!sourceDir) {
+    return [];
+  }
+
+  const collected: TextFileResource[] = [];
+  const seen = new Set<string>();
+
+  const add = (absolutePath: string, kind: TextFileKind) => {
+    const key = normalizePathForCompare(absolutePath);
+    if (seen.has(key)) return;
+    const resource = readTextFile(absolutePath, kind, sourceDir);
+    if (!resource) return;
+    seen.add(key);
+    collected.push(resource);
+  };
+
+  const declaration = readDeclarationFile(sourceDir);
+  if (declaration) {
+    seen.add(normalizePathForCompare(declaration.absolutePath));
+    collected.push(declaration);
+  }
+
+  const entries = record.entries ?? {};
+  for (const [key, value] of Object.entries(entries)) {
+    if (!value) continue;
+    const kind = ENTRY_KIND_BY_KEY[key] ?? 'other';
+    if (key === 'templates') {
+      for (const templateFile of expandTemplatesDir(value)) {
+        add(templateFile, 'template');
+      }
+      continue;
+    }
+    add(value, kind);
+  }
+
+  return collected;
+};
+
+/** Whether a file resource should be excluded from registry source records (declarations only). */
+export const isWorkspaceOnlyFile = (file: TextFileResource): boolean => file.kind === 'declaration';
+
+export const isRegistrySourceFile = (file: TextFileResource): file is RegistryTextFileResource => !isWorkspaceOnlyFile(file);

package/src/store/types.ts

@@ -0,0 +1,210 @@
+/**
+ * Normalized store abstraction.
+ *
+ * Both the workspace (filesystem) store and the future registry (database) store implement one
+ * read contract, so the docs read API and other consumers are storage-agnostic.
+ * Read methods are typed `Awaitable` so the filesystem implementation can stay synchronous
+ * while a database implementation is async behind the same interface.
+ *
+ * This module is types-only and provider-agnostic.
+ */
+
+import type { TokenSetKind } from '../registry/tokens/sets';
+import type { ComponentListObject, PageListObject, PatternListObject } from '../transformers/preview/types';
+
+/** A value that may be returned directly or as a promise. */
+export type Awaitable<T> = T | Promise<T>;
+
+/**
+ * Kind of a text source file tracked by the store. Mirrors the registry text-file model.
+ * `declaration` is **workspace-only** — registry stores never return it
+ * and declarations are synthesized on checkout.
+ */
+export type TextFileKind =
+  | 'declaration'
+  | 'component'
+  | 'template'
+  | 'style'
+  | 'script'
+  | 'story'
+  | 'docs'
+  | 'markdown'
+  | 'schema'
+  | 'other';
+
+export type RegistryTextFileKind = Exclude<TextFileKind, 'declaration'>;
+
+/**
+ * A normalized text source file belonging to a component or pattern. Used for checkout,
+ * inspection, and publish — never to rebuild previews during docs serving.
+ */
+export interface TextFileResource {
+  /** Registry-safe relative path of the file within the entity (e.g. `Badge.tsx`). */
+  path: string;
+  /** Absolute filesystem path the content was read from (workspace store only). */
+  absolutePath: string;
+  /** Classified file kind. */
+  kind: TextFileKind;
+  /** File content. */
+  content: string;
+  /** Content type to serve/transfer the file with. */
+  contentType: string;
+}
+
+export type RegistryTextFileResource = TextFileResource & { kind: RegistryTextFileKind };
+
+/**
+ * A reference to a source file resolvable by a store. For the filesystem store this is an
+ * absolute path; the contract keeps it opaque so a database store can use its own reference form.
+ */
+export interface SourceReference {
+  /** Absolute filesystem path (workspace store). */
+  absolutePath: string;
+}
+
+/**
+ * Read contract implemented by every component store backing. Consumers depend only on this so
+ * they never need to know whether the filesystem or a database is active.
+ */
+export interface ComponentStore {
+  /** All normalized component records, identical in shape to today's runtime records. */
+  list(): Awaitable<ComponentListObject[]>;
+  /** A single normalized component record by stable id, or `null` when absent. */
+  get(id: string): Awaitable<ComponentListObject | null>;
+  /** Read a source file by reference, or `null` when it cannot be resolved. */
+  getSource(ref: SourceReference): Awaitable<TextFileResource | null>;
+  /**
+   * The entity's declaration plus every `entries`-referenced source file, for checkout/publish.
+   * Returns an empty array when the entity is unknown.
+   */
+  getRelatedSourceFiles(id: string): Awaitable<TextFileResource[]>;
+}
+
+/**
+ * Read contract implemented by every pattern store backing. Same shape as {@link ComponentStore}
+ * over pattern records.
+ */
+export interface PatternStore {
+  /** All normalized pattern records, identical in shape to today's runtime records. */
+  list(): Awaitable<PatternListObject[]>;
+  /** A single normalized pattern record by stable id, or `null` when absent. */
+  get(id: string): Awaitable<PatternListObject | null>;
+  /** Read a source file by reference, or `null` when it cannot be resolved. */
+  getSource(ref: SourceReference): Awaitable<TextFileResource | null>;
+  /**
+   * The pattern's declaration plus every `entries`-referenced source file, for checkout/publish.
+   * Returns an empty array when the pattern is unknown.
+   */
+  getRelatedSourceFiles(id: string): Awaitable<TextFileResource[]>;
+}
+
+/**
+ * Read contract implemented by every page store backing. Same shape as {@link PatternStore} over
+ * page records. A page's single related source file is its verbatim `.md` (kind `markdown`).
+ */
+export interface PageStore {
+  /** All normalized page records. */
+  list(): Awaitable<PageListObject[]>;
+  /** A single normalized page record by stable id, or `null` when absent. */
+  get(id: string): Awaitable<PageListObject | null>;
+  /** Read a source file by reference, or `null` when it cannot be resolved. */
+  getSource(ref: SourceReference): Awaitable<TextFileResource | null>;
+  /** The page's verbatim `.md` source file, for checkout/publish. Empty when the page is unknown. */
+  getRelatedSourceFiles(id: string): Awaitable<TextFileResource[]>;
+}
+
+/**
+ * A logical token set as the store exposes it: its stable id, kind, and the exact extracted token
+ * slice (a `record` of `IColorObject[]`/…/`IFileComponentObject`). Consumers read the whole set and
+ * group/sort/look up in memory, so there is no individual-token accessor.
+ */
+export interface TokenSetRecord {
+  id: string;
+  kind: TokenSetKind;
+  record: unknown;
+}
+
+/** A generated token artifact (CSS/SCSS/Style Dictionary/types/custom output) as the store returns it. */
+export interface TokenArtifactResource {
+  /** Registry-safe relative output path under the tokens dir (e.g. `css/colors.css`). */
+  path: string;
+  /** Logical format label (`css`|`scss`|`types`|`styleDictionary`|custom). */
+  format: string;
+  content: string;
+  contentType: string;
+}
+
+/**
+ * Read contract implemented by every token store backing. The filesystem backing derives sets from
+ * the local `tokens.json` + generated files; the registry backing reads the `token_sets` /
+ * `token_artifacts` tables. Consumers depend only on this so token behavior is consistent across
+ * modes even though the storage differs.
+ */
+export interface TokenStore {
+  /** All logical token sets (three foundation sets + one per component). */
+  listSets(): Awaitable<TokenSetRecord[]>;
+  /** A single set by stable id, or `null` when absent. */
+  getSet(id: string): Awaitable<TokenSetRecord | null>;
+  /** Every generated artifact owned by a set. Empty when the set is unknown or has no output. */
+  getArtifacts(id: string): Awaitable<TokenArtifactResource[]>;
+  /** One generated artifact for a set by logical format, or `null` when absent. */
+  getArtifact(id: string, format: string): Awaitable<TokenArtifactResource | null>;
+}
+
+/**
+ * Lightweight metadata for one published asset. Collection/list reads return only this shape - never
+ * the binary body - so large collections do not produce oversized responses.
+ */
+export interface AssetMetadata {
+  /** Collection the asset belongs to (`icons`|`logos`|`fonts`). */
+  collection: string;
+  /** Registry-safe logical path within the collection (e.g. `assets/icons/add.svg`, `icons.zip`). */
+  path: string;
+  /** Human-facing asset name. */
+  name: string;
+  /** Content type to serve the asset with. */
+  contentType: string;
+  /** Byte length. */
+  size: number;
+  /** SHA-256 of the bytes (hex) - content identity + ETag. */
+  contentHash: string;
+  /** Free-form asset metadata carried from extraction (icon index, description, …). */
+  metadata?: Record<string, unknown> | null;
+}
+
+/**
+ * An asset's resolved content: inline bytes (filesystem store, or a DB-backed blob), or a redirect
+ * URL when an object-storage provider serves the content directly.
+ */
+export interface AssetContentResource extends AssetMetadata {
+  /** Inline bytes, when the content is served from the filesystem or an inline DB blob. */
+  body?: Buffer;
+  /** Signed/public provider URL to redirect to, when an object-storage provider serves the content. */
+  redirectUrl?: string;
+}
+
+/**
+ * Read contract implemented by every asset store backing. The filesystem backing derives collections
+ * from the generated `public/api` tree + archives; the registry backing reads the `assets` /
+ * `asset_collections` tables and resolves content through the configured storage provider. List
+ * methods return metadata only; content is fetched one asset at a time.
+ */
+export interface AssetStore {
+  /** All collections that have any published assets. */
+  listCollections(): Awaitable<string[]>;
+  /** Lightweight metadata for every asset in a collection (no bodies). Empty when unknown. */
+  listAssets(collection: string): Awaitable<AssetMetadata[]>;
+  /** Metadata for one asset by collection + logical path, or `null` when absent. */
+  getAsset(collection: string, path: string): Awaitable<AssetMetadata | null>;
+  /** One asset's resolved content (bytes or redirect), or `null` when absent. */
+  getAssetContent(collection: string, path: string): Awaitable<AssetContentResource | null>;
+}
+
+/** Convenience pairing of the stores backing one runtime. */
+export interface HandoffStore {
+  components: ComponentStore;
+  patterns: PatternStore;
+  pages: PageStore;
+  tokens: TokenStore;
+  assets: AssetStore;
+}

package/src/transformers/plugins/csf-render.ts

@@ -10,7 +10,15 @@ import Handoff from '../..';
 import { Logger } from '../../utils/logger';
 import { generateDocsArtifact, getPropertiesForComponentFromDocs } from '../docgen';
 import { SlotMetadata, SlotType } from '../preview/component';
-import { MAIN_COMPONENT_CSS_FILE } from '../preview/component/css';
+import {
+  renderComponentStyleLink,
+  renderGlobalScriptTag,
+  renderSharedStyleLinks,
+  resolveComponentArtifactPresence,
+  resolveSharedArtifactPresence,
+  type ComponentArtifactPresence,
+  type SharedArtifactPresence,
+} from '../preview/component/shared-artifacts';
 import { TransformComponentTokensResult } from '../preview/types';
 import { formatHtml, trimPreview } from '../utils/html';
 import { buildAndEvaluateModule } from '../utils/module';
@@ -266,14 +274,25 @@ function buildUsageSnippet(
   });
 }
 
-function createHtmlDocument(componentId: string, previewTitle: string, renderedHtml: string): string {
+function createHtmlDocument(
+  componentId: string,
+  previewTitle: string,
+  renderedHtml: string,
+  sharedArtifacts: SharedArtifactPresence,
+  componentArtifacts: ComponentArtifactPresence
+): string {
+  const basePath = process.env.HANDOFF_APP_BASE_PATH ?? '';
+  // Shared/global and component-owned artifacts are referenced only when present, so a CSF preview
+  // never requests an absent optional artifact. CSF previews stay static; the global script runs
+  // only for its top-level side effects when a global JS entry exists.
+  const sharedStyleLinks = renderSharedStyleLinks(sharedArtifacts, basePath);
+  const componentStyleLink = renderComponentStyleLink(componentArtifacts, componentId, basePath);
+  const globalScriptTag = renderGlobalScriptTag(sharedArtifacts, basePath);
   return `<!DOCTYPE html>
 <html lang="en">
   <head>
-    <meta charset="UTF-8" />
-    <link rel="stylesheet" href="${process.env.HANDOFF_APP_BASE_PATH ?? ''}/api/component/${MAIN_COMPONENT_CSS_FILE}" />
-    <link rel="stylesheet" href="${process.env.HANDOFF_APP_BASE_PATH ?? ''}/api/component/${componentId}.css" />
-    <link rel="stylesheet" href="${process.env.HANDOFF_APP_BASE_PATH ?? ''}/assets/css/preview.css" />
+    <meta charset="UTF-8" />${sharedStyleLinks ? `\n    ${sharedStyleLinks}` : ''}${componentStyleLink ? `\n    ${componentStyleLink}` : ''}
+    <link rel="stylesheet" href="${basePath}/assets/css/preview.css" />${globalScriptTag ? `\n    ${globalScriptTag}` : ''}
     <title>${previewTitle}</title>
   </head>
   <body>
@@ -425,6 +444,11 @@ export function csfRenderPlugin(
 
       componentData.properties = ensureIds(generatedProperties);
 
+      // Resolve which shared/global and component-owned artifacts exist so generated HTML references
+      // them only when present. These are built before component HTML, so this reflects final state.
+      const sharedArtifacts = resolveSharedArtifactPresence(handoff);
+      const componentArtifacts = resolveComponentArtifactPresence(handoff, componentId);
+
       let lastHtml = '';
       for (const [previewKey, preview] of Object.entries(componentData.previews)) {
         const storyKey = preview.sourcePreview && storyMap[preview.sourcePreview]
@@ -433,7 +457,7 @@ export function csfRenderPlugin(
         const storyValue = storyKey ? storyMap[storyKey] : undefined;
         const storyArgs = preview.values || {};
         const rendered = safeRenderToHtml(meta, storyValue, storyArgs);
-        const html = await formatHtml(createHtmlDocument(componentId, preview.title, rendered));
+        const html = await formatHtml(createHtmlDocument(componentId, preview.title, rendered, sharedArtifacts, componentArtifacts));
         const fileName = `${componentId}-${previewKey}.html`;
 
         this.emitFile({

package/src/transformers/plugins/handlebars-previews.ts

@@ -6,6 +6,12 @@ import { Plugin } from 'vite';
 import Handoff from '../..';
 import { Logger } from '../../utils/logger';
 import { TransformComponentTokensResult } from '../preview/types';
+import {
+  resolveComponentArtifactPresence,
+  resolveSharedArtifactPresence,
+  type ComponentArtifactPresence,
+  type SharedArtifactPresence,
+} from '../preview/component/shared-artifacts';
 import { createHandlebarsContext, registerHandlebarsHelpers } from '../utils/handlebars';
 import { formatHtmlWithWrapper, trimPreview } from '../utils/html';
 import { slugify } from '../utils/string';
@@ -70,7 +76,9 @@ async function renderHandlebarsTemplate(
   componentData: TransformComponentTokensResult,
   previewData: PreviewRenderData,
   injectFieldWrappers: boolean,
-  handoff: Handoff
+  handoff: Handoff,
+  sharedArtifacts: SharedArtifactPresence,
+  componentArtifacts: ComponentArtifactPresence
 ): Promise<string> {
   // Register Handlebars helpers with current injection state
   registerHandlebarsHelpers(
@@ -85,6 +93,8 @@ async function renderHandlebarsTemplate(
     title: componentData.title 
   }, previewData, {
     includeSharedStyles: Boolean(componentData.sharedStyles),
+    sharedArtifacts,
+    componentArtifacts,
   });
   
   const compiled = Handlebars.compile(template)(context);
@@ -173,6 +183,11 @@ export function handlebarsPreviewsPlugin(
 
       const generatedPreviews: { [key: string]: string } = {};
 
+      // Resolve which shared/global and component-owned artifacts exist so generated HTML references
+      // them only when present. These are built before component HTML, so this reflects final state.
+      const sharedArtifacts = resolveSharedArtifactPresence(handoff);
+      const componentArtifacts = resolveComponentArtifactPresence(handoff, componentId);
+
       // Generate previews for each variation
       for (const previewKey in componentData.previews) {
         try {
@@ -184,7 +199,9 @@ export function handlebarsPreviewsPlugin(
             componentData,
             previewData,
             false,
-            handoff
+            handoff,
+            sharedArtifacts,
+            componentArtifacts
           );
 
           const inspectModeHtml = await renderHandlebarsTemplate(
@@ -192,7 +209,9 @@ export function handlebarsPreviewsPlugin(
             componentData,
             previewData,
             true,
-            handoff
+            handoff,
+            sharedArtifacts,
+            componentArtifacts
           );
 
           // Emit preview files