handoff-app 1.1.3 → 1.2.0-0

package/src/app/components/Markdown/CodeHighlight.tsx

@@ -2,7 +2,7 @@ import { PreviewObject } from '@handoff/types/preview';
 // @ts-ignore
 import { CollapsibleTrigger } from '@radix-ui/react-collapsible';
 import { Select } from '@radix-ui/react-select';
-import { useEffect, useState } from 'react';
+import { useEffect, useMemo, useState } from 'react';
 import handlebars from 'react-syntax-highlighter/dist/esm/languages/prism/handlebars';
 import js from 'react-syntax-highlighter/dist/esm/languages/prism/javascript';
 import json from 'react-syntax-highlighter/dist/esm/languages/prism/json';
@@ -47,8 +47,8 @@ export const CodeHighlight: React.FC<{
   title?: string;
   language?: string;
   height?: string;
-  currentValues?: Record<string, string>;
-}> = ({ data, collapsible, type, title, dark, height, currentValues }) => {
+  currentPreviewUrl?: string;
+}> = ({ data, collapsible, type, title, dark, height, currentPreviewUrl }) => {
   const [isOpen, setIsOpen] = useState<boolean>(true);
 
   if (!data) {
@@ -69,7 +69,7 @@ export const CodeHighlight: React.FC<{
       format: 'html',
     };
   } else if (typeof data === 'string') {
-    data = data = {
+    data = {
       id: '',
       title: '',
       categories: [],
@@ -91,13 +91,26 @@ export const CodeHighlight: React.FC<{
   const metadataKeys = [
     'id', 'preview', 'image', 'categories', 'title', 'format',
     'description', 'type', 'group', 'tags', 'previews', 'properties',
-    'should_do', 'should_not_do', 'figma',
+    'should_do', 'should_not_do', 'figma', 'usage',
   ];
 
   const states = Object.keys(data)
     .filter((key) => !metadataKeys.includes(key) && !!(data as Record<string, any>)[key]);
-  const [activeState, setActiveState] = useState<string>(states[0]);
+  const hasPerPreviewUsage =
+    typeof data === 'object' &&
+    !!data.previews &&
+    Object.values(data.previews).some((preview) => !!preview?.usage);
+  const hasUsageState = (typeof data === 'object' && !!data.usage) || hasPerPreviewUsage;
+  const selectableStates = hasUsageState && !states.includes('usage') ? ['usage', ...states] : states;
+  const preferredState = selectableStates.includes('usage') ? 'usage' : selectableStates[0];
+  const [activeState, setActiveState] = useState<string>(preferredState);
   const [code, setCode] = useState<string>(data.html);
+  const stateResetKey = useMemo(() => {
+    if (typeof data === 'string') {
+      return `string:${type || 'html'}`;
+    }
+    return `${data.id || ''}|${data.title || ''}|${data.format || ''}|${Object.keys(data.previews || {}).join('|')}`;
+  }, [data, type]);
   const theme = dark ? oneDark : oneLight;
   theme['pre[class*="language-"]'].overflow = 'auto';
   theme['pre[class*="language-"]'].maxHeight = height ?? '450px';
@@ -118,6 +131,7 @@ export const CodeHighlight: React.FC<{
     sass: 'SASS',
     scss: 'SCSS',
     sharedStyles: 'Shared CSS',
+    usage: 'Usage',
     json: 'JSON',
     markdown: 'Markdown',
   };
@@ -167,6 +181,7 @@ export const CodeHighlight: React.FC<{
       css: 'css',
       sass: 'scss',
       sharedStyles: 'css',
+      usage: 'tsx',
       json: 'json',
       handlebars: 'handlebars',
       hbs: 'handlebars',
@@ -195,12 +210,43 @@ export const CodeHighlight: React.FC<{
     return jsxPatterns.some(pattern => pattern.test(code));
   };
 
+  const resolveUsageCode = (): string => {
+    if (typeof data !== 'object') {
+      return '';
+    }
+
+    if (currentPreviewUrl && data.previews) {
+      const activePreview = Object.values(data.previews).find((preview) => preview.url === currentPreviewUrl);
+      if (activePreview?.usage) {
+        return activePreview.usage;
+      }
+    }
+
+    const firstPreviewWithUsage = data.previews ? Object.values(data.previews).find((preview) => !!preview.usage) : undefined;
+    if (firstPreviewWithUsage?.usage) {
+      return firstPreviewWithUsage.usage;
+    }
+
+    return data.usage || '';
+  };
+
+  // Always default to usage for newly viewed component/code payloads.
+  // Users can still manually switch tabs after this initial selection.
+  useEffect(() => {
+    setActiveState(preferredState);
+  }, [preferredState, stateResetKey]);
+
   useEffect(() => {
     if (typeof data === 'string') {
       setCode(data);
       return;
     }
 
+    if (activeState === 'usage') {
+      setCode(resolveUsageCode());
+      return;
+    }
+
     if (activeState === 'code' && 'code' in data && !!data.code) {
       setCode(data.code);
       return;
@@ -209,7 +255,7 @@ export const CodeHighlight: React.FC<{
     if (activeState in data && !!(data as Record<string, any>)[activeState]) {
       setCode((data as Record<string, any>)[activeState]);
     }
-  }, [activeState, currentValues, data]);
+  }, [activeState, currentPreviewUrl, data]);
 
   return (
     <Collapsible id="code-samples" className="mt-4 space-y-2" style={{ maxWidth: '71vw' }} open={isOpen} onOpenChange={setIsOpen}>
@@ -219,14 +265,17 @@ export const CodeHighlight: React.FC<{
       >
         {title && <div>{title}</div>}
         <div className="flex items-center gap-2">
-          {states.length > 2 && (
+          {selectableStates.length > 1 && (
             <Select
-              defaultValue={activeState}
+              value={activeState}
               onValueChange={(key) => {
                 setActiveState(key);
                 if (typeof data === 'string') {
                   setCode(data);
                   return;
+                } else if (key === 'usage') {
+                  setCode(resolveUsageCode());
+                  return;
                 } else {
                   setCode(data[key]);
                 }
@@ -236,8 +285,8 @@ export const CodeHighlight: React.FC<{
                 <SelectValue placeholder="Code View" />
               </SelectTrigger>
               <SelectContent>
-                {states
-                  .filter((value) => ['code', 'html', 'css', 'js', 'sass', 'sharedStyles'].includes(value))
+                {selectableStates
+                  .filter((value) => ['usage', 'code', 'html', 'css', 'js', 'sass', 'sharedStyles'].includes(value))
                   .map((state) => {
                     return (
                       <SelectItem key={state} value={state}>

package/src/app/components/util/index.ts

@@ -1,4 +1,4 @@
-import { ComponentListObject, ComponentType } from '@handoff/transformers/preview/types';
+import { ComponentListObject, ComponentType, PatternListObject } from '@handoff/transformers/preview/types';
 import { ClientConfig, RuntimeConfig } from '@handoff/types/config';
 import { ComponentDocumentationOptions, PreviewObject } from '@handoff/types/preview';
 import * as fs from 'fs-extra';
@@ -85,7 +85,7 @@ export const knownPaths = [
   'assets/logos',
   'foundations',
   'foundations/colors',
-  'foundations/icons',
+  'foundations/icons',  
   'foundations/effects',
   'foundations/logos',
   'foundations/logo',
@@ -98,6 +98,7 @@ export const knownPaths = [
   'system/tokens/foundations/effects',
   'system/tokens/foundations/typography',
   'system/tokens/components',
+  'system/pattern',
 ];
 
 /**
@@ -266,6 +267,16 @@ export const staticBuildMenu = () => {
                   menu: staticBuildTokensMenu(),
                 };
               }
+              if (sub.patterns) {
+                const patternMenu = staticBuildPatternMenu();
+                if (patternMenu.length > 0) {
+                  return {
+                    title: sub.title || 'Patterns',
+                    menu: patternMenu,
+                  };
+                }
+                return undefined;
+              }
               if (sub.enabled !== false) {
                 return sub;
               }
@@ -413,6 +424,64 @@ const staticBuildTokenMenu = () => {
   return subSections;
 };
 
+/**
+ * Fetch patterns from the patterns.json API file
+ */
+export const fetchPatterns = (): { id: string; title: string; description: string; group: string }[] => {
+  const patternsFilePath = path.resolve(
+    process.env.HANDOFF_MODULE_PATH ?? '',
+    '.handoff',
+    `${process.env.HANDOFF_PROJECT_ID}`,
+    'public',
+    'api',
+    'patterns.json'
+  );
+
+  if (!fs.existsSync(patternsFilePath)) {
+    return [];
+  }
+
+  try {
+    const patternList = JSON.parse(
+      fs.readFileSync(patternsFilePath, 'utf-8')
+    ) as PatternListObject[];
+
+    return patternList.map((p) => ({
+      id: p.id,
+      title: p.title || '',
+      description: p.description || '',
+      group: p.group || '',
+    }));
+  } catch {
+    return [];
+  }
+};
+
+const staticBuildPatternMenu = () => {
+  const basePath = buildBasePath();
+  const patterns = fetchPatterns();
+
+  if (patterns.length === 0) return [];
+
+  const grouped = groupBy(patterns, (p) => p.group ?? '');
+  let menu: { title: string; menu: { path: string; title: string }[] }[] = [];
+
+  Object.keys(grouped).forEach((group) => {
+    const menuGroup = { title: group || 'Uncategorized', menu: [] as { path: string; title: string }[] };
+    grouped[group].forEach((pattern) => {
+      menuGroup.menu.push({
+        path: `${basePath}system/pattern/${pattern.id}`,
+        title: pattern.title || startCase(pattern.id),
+      });
+    });
+    menuGroup.menu.sort((a, b) => a.title.localeCompare(b.title));
+    menu.push(menuGroup);
+  });
+
+  menu.sort((a, b) => a.title.localeCompare(b.title));
+  return menu;
+};
+
 /**
  * Filter the menus by the current path
  * @param menu

package/src/app/pages/system/pattern/[pattern]/index.tsx

@@ -0,0 +1,223 @@
+'use client';
+import { PatternListObject } from '@handoff/transformers/preview/types';
+import { startCase } from 'lodash';
+import React, { useCallback, useEffect, useState } from 'react';
+import ReactMarkdown from 'react-markdown';
+import rehypeRaw from 'rehype-raw';
+import Layout from '../../../../components/Layout/Main';
+import { MarkdownComponents } from '../../../../components/Markdown/MarkdownComponents';
+import PrevNextNav from '../../../../components/Navigation/PrevNextNav';
+import HeadersType from '../../../../components/Typography/Headers';
+import {
+  DocumentationProps,
+  fetchPatterns,
+  getClientRuntimeConfig,
+  getCurrentSection,
+  IParams,
+  staticBuildMenu,
+} from '../../../../components/util';
+
+type PatternNavItem = { id: string; title: string; description: string; group: string };
+
+interface PatternPageProps extends DocumentationProps {
+  id: string;
+  previousPattern: PatternNavItem | null;
+  nextPattern: PatternNavItem | null;
+}
+
+export async function getStaticPaths() {
+  return {
+    paths: fetchPatterns()?.map((p) => ({ params: { pattern: p.id } })) ?? [],
+    fallback: false,
+  };
+}
+
+export const getStaticProps = async (context: { params: IParams }) => {
+  const { pattern: patternId } = context.params;
+  const patterns = fetchPatterns() ?? [];
+  const menu = staticBuildMenu();
+  const config = getClientRuntimeConfig();
+  const patternData = patterns.find((p) => p.id === patternId);
+
+  const sameGroupPatterns = patterns.filter((p) => p.group === patternData?.group);
+  const groupIndex = sameGroupPatterns.findIndex((p) => p.id === patternId);
+  const previousPattern = sameGroupPatterns[groupIndex - 1] ?? null;
+  const nextPattern = sameGroupPatterns[groupIndex + 1] ?? null;
+
+  const fallbackTitle = patternData?.title || startCase(patternId as string);
+
+  return {
+    props: {
+      id: patternId,
+      menu,
+      config,
+      current: getCurrentSection(menu, '/system') ?? [],
+      metadata: {
+        title: fallbackTitle,
+        description: patternData?.description || '',
+        metaTitle: `${fallbackTitle}${config?.app?.client ? ` | ${config.app.client} Design System` : ''}`,
+        metaDescription: patternData?.description || '',
+      },
+      previousPattern,
+      nextPattern,
+    },
+  };
+};
+
+const PatternPage = ({ menu, metadata, current, id, config, previousPattern, nextPattern }: PatternPageProps) => {
+  const [pattern, setPattern] = useState<PatternListObject | undefined>(undefined);
+  const [fetchError, setFetchError] = useState<string | undefined>(undefined);
+  const [iframeHeight, setIframeHeight] = useState('400px');
+  const iframeRef = React.useRef<HTMLIFrameElement>(null);
+
+  const appBasePath = process.env.HANDOFF_APP_BASE_PATH ?? '';
+  const normalizedBasePath = appBasePath ? `/${appBasePath.replace(/^\/+|\/+$/g, '')}` : '';
+  const patternRoute = (patternId: string) => `${normalizedBasePath}/system/pattern/${patternId}`;
+
+  const previousLink = previousPattern
+    ? { href: patternRoute(previousPattern.id), title: previousPattern.title }
+    : null;
+  const nextLink = nextPattern
+    ? { href: patternRoute(nextPattern.id), title: nextPattern.title }
+    : null;
+  const invalidComponents = pattern?.components?.filter((comp) => comp.resolved === false) ?? [];
+
+  useEffect(() => {
+    const controller = new AbortController();
+    setPattern(undefined);
+    setFetchError(undefined);
+
+    fetch(`${normalizedBasePath}/api/pattern/${id}.json`, { signal: controller.signal })
+      .then((res) => {
+        if (!res.ok) throw new Error(`Failed to load pattern: ${res.status} ${res.statusText}`);
+        return res.json();
+      })
+      .then((data) => setPattern(data as PatternListObject))
+      .catch((err) => {
+        if (err.name !== 'AbortError') {
+          setFetchError(err instanceof Error ? err.message : 'Failed to load pattern data.');
+        }
+      });
+
+    return () => controller.abort();
+  }, [id, normalizedBasePath]);
+
+  const onIframeLoad = useCallback(() => {
+    if (iframeRef.current?.contentWindow?.document?.body) {
+      setIframeHeight(iframeRef.current.contentWindow.document.body.scrollHeight + 'px');
+    }
+  }, []);
+
+  if (fetchError) return <p className="p-4 text-red-500">{fetchError}</p>;
+  if (!pattern) return <p>Loading...</p>;
+
+  return (
+    <Layout config={config} menu={menu} current={current} metadata={metadata}>
+      <div className="flex flex-col gap-3 pb-14">
+        <small className="text-sm font-medium text-sky-600 dark:text-gray-300">Patterns</small>
+        <HeadersType.H1>{metadata.title}</HeadersType.H1>
+        {metadata.description && (
+          <div className="prose max-w-[800px] text-xl font-light leading-relaxed text-gray-600 dark:text-gray-300">
+            <ReactMarkdown components={MarkdownComponents} rehypePlugins={[rehypeRaw]}>
+              {metadata.description}
+            </ReactMarkdown>
+          </div>
+        )}
+      </div>
+
+      <div className="max-w-[1100px]">
+        {/* Pattern composition info */}
+        <div className="mb-4 flex items-center gap-2 text-sm text-gray-500">
+          <span>{pattern.components?.length ?? 0} component(s)</span>
+          {pattern.group && (
+            <>
+              <span className="text-gray-300">|</span>
+              <span>{pattern.group}</span>
+            </>
+          )}
+        </div>
+
+        {invalidComponents.length > 0 && (
+          <div className="mb-4 rounded-lg border border-amber-300 bg-amber-50 px-4 py-3 text-sm text-amber-900 dark:border-amber-800 dark:bg-amber-950/40 dark:text-amber-200">
+            {invalidComponents.length} pattern component{invalidComponents.length > 1 ? 's could' : ' could'} not be resolved and {invalidComponents.length > 1 ? 'were' : 'was'} skipped.
+          </div>
+        )}
+
+        {/* Full-page pattern preview */}
+        <div className="rounded-lg border border-gray-200 dark:border-gray-900">
+          <div className="flex w-full items-center justify-between rounded-t-lg bg-gray-50 px-6 py-2 dark:bg-gray-800">
+            <p className="font-monospace text-[11px] text-accent-foreground">Pattern Preview</p>
+          </div>
+          <div className="dotted-bg w-full p-4">
+            {pattern.url ? (
+              <iframe
+                ref={iframeRef}
+                onLoad={onIframeLoad}
+                height={iframeHeight}
+                style={{
+                  width: '100%',
+                  height: iframeHeight,
+                  display: 'block',
+                  border: 'none',
+                }}
+                src={`${normalizedBasePath}/api/pattern/${pattern.url}`}
+              />
+            ) : (
+              <div className="flex items-center justify-center p-8 text-sm text-gray-500">
+                No preview available for this pattern.
+              </div>
+            )}
+          </div>
+        </div>
+
+        {/* Component list */}
+        {pattern.components && pattern.components.length > 0 && (
+          <div className="mt-8">
+            <HeadersType.H3>Components in this pattern</HeadersType.H3>
+            <div className="mt-4 overflow-hidden rounded-lg border border-gray-200 dark:border-gray-800">
+              <table className="w-full text-sm">
+                <thead className="border-b bg-gray-50 dark:bg-gray-800">
+                  <tr>
+                    <th className="px-4 py-2 text-left font-medium text-gray-600 dark:text-gray-300">Component</th>
+                    <th className="px-4 py-2 text-left font-medium text-gray-600 dark:text-gray-300">Preview</th>
+                    <th className="px-4 py-2 text-left font-medium text-gray-600 dark:text-gray-300">Status</th>
+                    <th className="px-4 py-2 text-left font-medium text-gray-600 dark:text-gray-300">Custom Args</th>
+                  </tr>
+                </thead>
+                <tbody>
+                  {pattern.components.map((comp, i) => (
+                    <tr key={`${comp.id}-${i}`} className="border-b last:border-b-0 dark:border-gray-800">
+                      <td className="px-4 py-2 font-mono text-xs">{comp.id}</td>
+                      <td className="px-4 py-2 text-xs text-gray-500">
+                        {comp.preview || comp.resolvedPreview || 'default'}
+                      </td>
+                      <td className="px-4 py-2 text-xs">
+                        {comp.resolved === false ? (
+                          <span className="inline-flex w-fit rounded-full bg-amber-100 px-2 py-0.5 text-[11px] font-medium text-amber-800 dark:bg-amber-900/60 dark:text-amber-200">
+                            Unresolved
+                          </span>
+                        ) : (
+                          <span className="inline-flex w-fit rounded-full bg-emerald-100 px-2 py-0.5 text-[11px] font-medium text-emerald-800 dark:bg-emerald-900/60 dark:text-emerald-200">
+                            OK
+                          </span>
+                        )}
+                      </td>
+                      <td className="px-4 py-2 text-xs text-gray-500">
+                        {comp.args ? JSON.stringify(comp.args) : '-'}
+                      </td>
+                    </tr>
+                  ))}
+                </tbody>
+              </table>
+            </div>
+          </div>
+        )}
+
+        <hr className="mt-8" />
+        <PrevNextNav previous={previousLink} next={nextLink} />
+      </div>
+    </Layout>
+  );
+};
+
+export default PatternPage;

package/src/app/pages/system/pattern/index.tsx

@@ -0,0 +1,14 @@
+import { useRouter } from 'next/router';
+import { useEffect } from 'react';
+
+const PatternIndexRedirect = () => {
+  const router = useRouter();
+
+  useEffect(() => {
+    router.replace('/system');
+  }, [router]);
+
+  return null;
+};
+
+export default PatternIndexRedirect;

package/src/app-builder/README.md

@@ -1,14 +1,42 @@
 # App Builder Module
 
-Handles building, watching, and serving the Next.js documentation application.
+Builds and runs the Next.js documentation app from runtime config + generated preview output.
 
-## Files
+## End-to-End Flow
 
-| File | Purpose |
+1. **Initialize app shell** (`build.ts`)
+   - Prepare `.handoff/<project>/app`, copy app sources, sync `public`, persist client config.
+
+2. **Build component artifacts**
+   - Production: `buildComponents` + `buildPatterns`.
+   - Watch mode: `processComponents(..., { useCache: true })` to skip unchanged components.
+
+3. **Build global bundles**
+   - Build main JS/CSS entry bundles when configured.
+
+4. **Run/watch**
+   - Production: run `next build` and publish static output.
+   - Watch: run `next dev` + WebSocket + chokidar watchers.
+
+5. **Incremental rebuild behavior** (`watchers.ts`)
+   - Source entry change -> targeted component segment rebuild.
+   - Main config/global entry change -> full component rebuild.
+   - Pattern config change -> diff-aware selective preview rebuild only for affected components.
+   - After component rebuilds -> run config-diff finalizers (e.g. pattern composition).
+
+6. **Event coalescing**
+   - Watchers share a single scheduler lock; rapid updates from the same source coalesce.
+
+## Key Files
+
+| Path | Purpose |
 |------|---------|
-| `build.ts` | `buildApp()` — production build; `watchApp()` — dev server with watchers; `devApp()` — bare Next.js dev |
-| `websocket.ts` | `createWebSocketServer()` — WebSocket server for dev hot-reloading |
-| `paths.ts` | `getAppPath()`, `getWorkingPublicPath()`, `syncPublicFiles()` |
-| `client-config.ts` | `persistClientConfig()`, `generateTokensApi()` |
-| `watchers.ts` | File watchers for public dir, pages, global entries (SCSS/JS), runtime components, and config |
-| `index.ts` | Barrel re-exports |
+| `build.ts` | `buildApp()`, `watchApp()`, `devApp()` orchestration |
+| `watchers.ts` | Watcher orchestration and rebuild routing |
+| `watchers/component.ts` | Runtime component path mapping + segment resolution helpers |
+| `watchers/utils.ts` | Coalescing scheduler + watcher state |
+| `config-diff/index.ts` | Diff strategy exports + registry/finalizers |
+| `config-diff/strategies/pattern.ts` | Pattern snapshot/diff/apply strategy |
+| `client-config.ts` | Persist client runtime config + token API payload |
+| `paths.ts` | App/public path helpers + public sync |
+| `websocket.ts` | Dev reload WebSocket server |

package/src/app-builder/build.ts

@@ -3,6 +3,7 @@ import fs from 'fs-extra';
 import path from 'path';
 import Handoff from '..';
 import { buildComponents } from '../pipeline/components';
+import { buildPatterns } from '../pipeline/patterns';
 import { buildMainCss } from '../transformers/preview/component/css';
 import { buildMainJS } from '../transformers/preview/component/javascript';
 import processComponents from '../transformers/preview/component/builder';
@@ -90,9 +91,10 @@ const buildApp = async (handoff: Handoff, skipComponents?: boolean): Promise<voi
   // Perform cleanup
   await cleanupAppDirectory(handoff);
 
-  // Build components
+  // Build components, then patterns (patterns depend on component output)
   if (!skipComponents) {
     await buildComponents(handoff);
+    await buildPatterns(handoff);
   }
 
   // Prepare app
@@ -143,6 +145,9 @@ export const watchApp = async (handoff: Handoff): Promise<void> => {
   await buildMainJS(handoff);
   await buildMainCss(handoff);
 
+  // Build patterns after components are ready
+  await buildPatterns(handoff);
+
   const appPath = await initializeProjectApp(handoff);
 
   // Persist client configuration
@@ -190,7 +195,8 @@ export const watchApp = async (handoff: Handoff): Promise<void> => {
   };
 
   const state: WatcherState = {
-    debounce: false,
+    busy: false,
+    pendingHandlers: new Map(),
     runtimeComponentsWatcher: null,
     runtimeConfigurationWatcher: null,
     componentDirectoriesWatcher: null,

package/src/app-builder/config-diff/index.ts

@@ -0,0 +1,4 @@
+export type { ConfigDiffStrategy, RebuildHandle } from './types';
+export { type MapSnapshot, diffMapSnapshots, stableStringify } from './snapshot';
+export { patternDiffStrategy } from './strategies/pattern';
+export { getAllStrategies, getStrategy, runAllFinalizers } from './registry';

package/src/app-builder/config-diff/registry.ts

@@ -0,0 +1,23 @@
+import Handoff from '../..';
+import { patternDiffStrategy } from './strategies/pattern';
+import { ConfigDiffStrategy } from './types';
+
+const strategies = new Map<string, ConfigDiffStrategy>([
+  [patternDiffStrategy.kind, patternDiffStrategy],
+]);
+
+export const getStrategy = (kind: string): ConfigDiffStrategy | undefined =>
+  strategies.get(kind);
+
+export const getAllStrategies = (): ConfigDiffStrategy[] =>
+  Array.from(strategies.values());
+
+/**
+ * Runs every registered strategy finalizer.
+ * Called after component rebuilds so derived artifacts stay up-to-date.
+ */
+export const runAllFinalizers = async (handoff: Handoff): Promise<void> => {
+  for (const strategy of strategies.values()) {
+    await strategy.finalize(handoff);
+  }
+};

package/src/app-builder/config-diff/snapshot.ts

@@ -0,0 +1,51 @@
+/** outerKey -> Map<innerKey, serializedValue> */
+export type MapSnapshot = Map<string, Map<string, string>>;
+
+/**
+ * Deterministic JSON serializer that sorts object keys at every nesting level.
+ * Prevents false-positive diffs when identical values are constructed with
+ * different key insertion order across reloads.
+ */
+export const stableStringify = (value: unknown): string =>
+  JSON.stringify(value, (_, v) =>
+    v && typeof v === 'object' && !Array.isArray(v)
+      ? Object.fromEntries(Object.entries(v).sort(([a], [b]) => a.localeCompare(b)))
+      : v
+  );
+
+/**
+ * Compares two MapSnapshots and returns the outer keys where the inner maps
+ * differ (added, removed, or values changed).
+ */
+export const diffMapSnapshots = (
+  oldSnapshot: MapSnapshot,
+  newSnapshot: MapSnapshot
+): string[] => {
+  const affected = new Set<string>();
+
+  for (const [key, oldEntries] of oldSnapshot) {
+    const newEntries = newSnapshot.get(key);
+    if (!newEntries) {
+      affected.add(key);
+      continue;
+    }
+    if (oldEntries.size !== newEntries.size) {
+      affected.add(key);
+      continue;
+    }
+    for (const [subKey, oldValue] of oldEntries) {
+      if (newEntries.get(subKey) !== oldValue) {
+        affected.add(key);
+        break;
+      }
+    }
+  }
+
+  for (const key of newSnapshot.keys()) {
+    if (!oldSnapshot.has(key)) {
+      affected.add(key);
+    }
+  }
+
+  return Array.from(affected);
+};