@harpy-js/core 0.4.7

package/src/core/client-component-wrapper.ts

@@ -0,0 +1,72 @@
+import React from "react";
+
+/**
+ * Generates a unique instance ID (browser-compatible version)
+ */
+function generateInstanceId(prefix: string): string {
+  // Use Math.random for browser compatibility
+  const randomId = Math.random().toString(36).substring(2, 11);
+  return `${prefix}-${randomId}`;
+}
+
+/**
+ * Global tracker for registering components on the server side
+ * This is set by the JSX engine during server-side rendering
+ */
+declare global {
+  var __COMPONENT_REGISTRY__: ((data: any) => void) | undefined;
+}
+
+/**
+ * Wrapper that enables automatic hydration for components marked with 'use client'.
+ *
+ * This works on both server and browser:
+ * - Server: Creates a hydration container with props and calls the registration function if available
+ * - Browser: Creates the same hydration container for client-side hydration
+ */
+export function autoWrapClientComponent<T extends React.ComponentType<any>>(
+  Component: T,
+  componentName: string,
+): React.ComponentType<React.ComponentProps<T>> {
+  const WrappedComponent = (props: React.ComponentProps<T>) => {
+    // Generate a unique instance ID for this component instance
+    const instanceId = generateInstanceId(`hydrate-${componentName}`);
+
+    // Register on server side if registry is available
+    console.log(
+      `[Wrapper] Rendering ${componentName}, registry available:`,
+      typeof global !== "undefined" && !!global.__COMPONENT_REGISTRY__,
+    );
+    if (typeof global !== "undefined" && global.__COMPONENT_REGISTRY__) {
+      console.log(
+        `[Wrapper] Registering ${componentName} with id ${instanceId}`,
+      );
+      global.__COMPONENT_REGISTRY__({
+        componentPath: "",
+        componentName,
+        instanceId,
+        props: props as Record<string, any>,
+      });
+    }
+
+    // Store props in a script tag for client-side hydration access
+    const propsJson = JSON.stringify(props);
+
+    return React.createElement(
+      "div",
+      {
+        id: instanceId,
+        suppressHydrationWarning: true,
+      },
+      React.createElement(Component, props),
+      React.createElement("script", {
+        type: "application/json",
+        id: `${instanceId}-props`,
+        dangerouslySetInnerHTML: { __html: propsJson },
+      }),
+    );
+  };
+
+  WrappedComponent.displayName = `ClientComponent(${componentName})`;
+  return WrappedComponent;
+}

package/src/core/client-hydration.tsx

@@ -0,0 +1,99 @@
+/**
+ * Client-side hydration entry point.
+ * This script is injected into the HTML and runs in the browser to hydrate interactive components.
+ */
+
+import React from "react";
+
+/**
+ * Client-side hydration entry point.
+ * This script is injected into the HTML and runs in the browser to hydrate interactive components.
+ */
+
+interface HydrationMarker {
+  componentName: string;
+  instanceId: string;
+  propsId: string;
+}
+
+/**
+ * Finds all hydration markers in the DOM and returns their data
+ */
+function findHydrationMarkers(): HydrationMarker[] {
+  const markers: HydrationMarker[] = [];
+
+  // Find all divs with id starting with 'hydrate-'
+  const hydrationDivs = document.querySelectorAll('div[id^="hydrate-"]');
+
+  hydrationDivs.forEach((div) => {
+    const instanceId = div.id;
+    // Parse instanceId: "hydrate-ComponentName-uniqueid"
+    const match = instanceId.match(/^hydrate-([^-]+)-(.+)$/);
+
+    if (match) {
+      const componentName = match[1];
+      const propsScriptId = `${instanceId}-props`;
+
+      markers.push({
+        componentName,
+        instanceId,
+        propsId: propsScriptId,
+      });
+    }
+  });
+
+  return markers;
+}
+
+/**
+ * Gets props for a hydration marker from the embedded script tag
+ */
+function getHydrationProps(propsId: string): Record<string, any> {
+  const propsScript = document.getElementById(propsId);
+  if (!propsScript) return {};
+
+  try {
+    return JSON.parse(propsScript.textContent || "{}");
+  } catch (e) {
+    console.warn(`Failed to parse props for ${propsId}:`, e);
+    return {};
+  }
+}
+
+/**
+ * Hydrates a single client component
+ * This is called by the bundled component chunk scripts
+ */
+export function hydrateComponent(
+  componentName: string,
+  Component: React.ComponentType<any>,
+) {
+  const markers = findHydrationMarkers();
+  const relevantMarkers = markers.filter(
+    (m) => m.componentName === componentName,
+  );
+
+  relevantMarkers.forEach((marker) => {
+    const container = document.getElementById(marker.instanceId);
+    if (!container) {
+      console.warn(`Hydration container not found for ${marker.instanceId}`);
+      return;
+    }
+
+    const props = getHydrationProps(marker.propsId);
+
+    // Dynamically import React for hydration
+    Promise.all([import("react-dom/client")]).then(([{ hydrateRoot }]) => {
+      try {
+        hydrateRoot(container, React.createElement(Component, props));
+      } catch (error) {
+        console.error(`Failed to hydrate component ${componentName}:`, error);
+      }
+    });
+  });
+}
+
+// Export for use in component bundles
+if (typeof window !== "undefined") {
+  (window as any).__HYDRATION__ = { hydrateComponent };
+}

package/src/core/client-wrapper-browser.ts

@@ -0,0 +1,40 @@
+/**
+ * Browser-safe version of client component wrapper
+ * This version is used only for client-side hydration and doesn't import Node modules
+ */
+
+import React from "react";
+
+/**
+ * Browser-compatible instance ID generator
+ */
+function generateBrowserInstanceId(prefix: string): string {
+  const randomId = Math.random().toString(36).substring(2, 11);
+  return `${prefix}-${randomId}`;
+}
+
+/**
+ * Client-side wrapper for hydration
+ * Used during client-side hydration to wrap components
+ */
+export function hydrateClientComponent<T extends React.ComponentType<any>>(
+  Component: T,
+  componentName: string,
+  props: Record<string, any>,
+): React.ReactElement {
+  const instanceId = generateBrowserInstanceId(`hydrate-${componentName}`);
+
+  return React.createElement(
+    "div",
+    {
+      id: instanceId,
+      suppressHydrationWarning: true,
+    },
+    React.createElement(Component, props),
+    React.createElement("script", {
+      type: "application/json",
+      id: `${instanceId}-props`,
+      dangerouslySetInnerHTML: { __html: JSON.stringify(props) },
+    }),
+  );
+}

package/src/core/component-analyzer.ts

@@ -0,0 +1,89 @@
+import * as fs from "fs";
+import * as path from "path";
+
+/**
+ * Detects if a component file has the 'use client' directive
+ */
+export function hasUseClientDirective(filePath: string): boolean {
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    // Match "use client" directive at the start of the file, possibly after comments
+    const useClientRegex = /^(['"]use client['"];?\s*)/m;
+    return useClientRegex.test(content);
+  } catch (error) {
+    console.error(`Error reading file ${filePath}:`, error);
+    return false;
+  }
+}
+
+/**
+ * Get the component name from file path
+ * Example: /src/features/home/views/counter.tsx -> Counter (converted from counter)
+ */
+export function getComponentNameFromPath(filePath: string): string {
+  const fileName = path.basename(filePath, path.extname(filePath));
+  // Convert kebab-case to PascalCase
+  return fileName
+    .split("-")
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join("");
+}
+
+/**
+ * Recursively find all component files (.tsx/.ts) in a directory
+ */
+export function findComponentFiles(
+  dir: string,
+  exclude: string[] = [],
+): string[] {
+  const components: string[] = [];
+
+  function traverse(currentPath: string) {
+    try {
+      const files = fs.readdirSync(currentPath);
+
+      for (const file of files) {
+        const fullPath = path.join(currentPath, file);
+        const stat = fs.statSync(fullPath);
+
+        // Skip excluded paths
+        if (exclude.some((ex) => fullPath.includes(ex))) {
+          continue;
+        }
+
+        if (stat.isDirectory()) {
+          traverse(fullPath);
+        } else if (file.endsWith(".tsx") || file.endsWith(".ts")) {
+          // Only include files that export components (convention: in views/ or end with Component)
+          if (
+            fullPath.includes("/views/") ||
+            file.endsWith(".component.ts") ||
+            file.endsWith(".component.tsx")
+          ) {
+            components.push(fullPath);
+          }
+        }
+      }
+    } catch (error) {
+      console.error(`Error traversing directory ${currentPath}:`, error);
+    }
+  }
+
+  traverse(dir);
+  return components;
+}
+
+/**
+ * Get client components from source directory
+ */
+export function getClientComponents(srcDir: string): string[] {
+  const components = findComponentFiles(srcDir, [
+    "/node_modules/",
+    "/dist/",
+    "/test/",
+    "/core/", // Exclude internal framework code
+  ]);
+  return components.filter((componentPath) =>
+    hasUseClientDirective(componentPath),
+  );
+}

package/src/core/component-auto-wrapper.ts

@@ -0,0 +1,68 @@
+/**
+ * Auto-wrapping system for components with 'use client' directive.
+ *
+ * This module provides utilities to automatically detect and wrap client components
+ * without requiring manual withClientComponent() calls in application code.
+ *
+ * The wrapping happens transparently at the component definition level.
+ */
+
+import * as fs from "fs";
+import React from "react";
+import { autoWrapClientComponent } from "./client-component-wrapper";
+import { getComponentNameFromPath } from "./component-analyzer";
+
+/**
+ * Cache of file paths and whether they have 'use client' directive
+ * Key: absolute file path, Value: boolean indicating presence of 'use client'
+ */
+const clientComponentCache = new Map<string, boolean>();
+
+/**
+ * Detects if a source file has 'use client' directive
+ */
+function hasUseClientDirective(filePath: string): boolean {
+  if (clientComponentCache.has(filePath)) {
+    return clientComponentCache.get(filePath)!;
+  }
+
+  try {
+    const content = fs.readFileSync(filePath, "utf-8");
+    // Match "use client" at the very start of the file
+    const hasDirective = /^(['"]use client['"];?\s*)/m.test(content);
+    clientComponentCache.set(filePath, hasDirective);
+    return hasDirective;
+  } catch (error) {
+    clientComponentCache.set(filePath, false);
+    return false;
+  }
+}
+
+/**
+ * Wraps a component if its source file contains 'use client' directive.
+ * This is the recommended way to use client components - just export them normally
+ * with 'use client' at the top, and they'll be auto-wrapped.
+ *
+ * Usage:
+ *   export default autoWrap(MyComponent, import.meta.url);
+ *
+ * Or better yet, use the custom hook approach in component-client.ts
+ */
+export function autoWrap<T extends React.ComponentType<any>>(
+  Component: T,
+  fileUrl: string,
+): T {
+  // Convert URL to file path
+  const filePath = fileUrl.replace("file://", "");
+
+  // If this component file doesn't have 'use client', return it unwrapped
+  if (!hasUseClientDirective(filePath)) {
+    return Component;
+  }
+
+  // Get component name from file path
+  const componentName = getComponentNameFromPath(filePath);
+
+  // Wrap for auto-hydration
+  return autoWrapClientComponent(Component, componentName) as T;
+}

package/src/core/component-client-wrapper.ts

@@ -0,0 +1,112 @@
+/**
+ * Smart component export wrapper that automatically detects 'use client' directive
+ * and applies hydration wrapping without requiring manual withClientComponent() calls.
+ *
+ * This simulates Next.js's automatic client component handling.
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+import React from "react";
+import { autoWrapClientComponent } from "./client-component-wrapper";
+import { getComponentNameFromPath } from "./component-analyzer";
+
+/**
+ * Cache to avoid re-reading files repeatedly
+ */
+const componentCache = new Map<
+  string,
+  {
+    isClientComponent: boolean;
+    wrappedComponent: React.ComponentType<any> | null;
+  }
+>();
+
+/**
+ * Check if a file has 'use client' directive by reading the source
+ */
+function detectClientComponent(sourceFilePath: string): {
+  isClientComponent: boolean;
+  componentPath: string;
+} {
+  // Normalize the path
+  const normalizedPath = path.resolve(sourceFilePath);
+
+  if (componentCache.has(normalizedPath)) {
+    const cached = componentCache.get(normalizedPath)!;
+    return {
+      isClientComponent: cached.isClientComponent,
+      componentPath: normalizedPath,
+    };
+  }
+
+  let isClientComponent = false;
+
+  try {
+    const content = fs.readFileSync(normalizedPath, "utf-8");
+    isClientComponent = /^['"]use client['"];?\s*/.test(content);
+  } catch (error) {
+    // File doesn't exist or can't be read - treat as server component
+    isClientComponent = false;
+  }
+
+  componentCache.set(normalizedPath, {
+    isClientComponent,
+    wrappedComponent: null,
+  });
+
+  return { isClientComponent, componentPath: normalizedPath };
+}
+
+/**
+ * Higher-order component that automatically wraps client components.
+ *
+ * Usage in component files:
+ * ```tsx
+ * 'use client';
+ *
+ * function MyComponent() { ... }
+ * export default createClientComponent(MyComponent, __filename);
+ * ```
+ *
+ * The __filename reference will be resolved at build time or runtime.
+ * This function detects the 'use client' directive and wraps accordingly.
+ */
+export function createClientComponent<T extends React.ComponentType<any>>(
+  Component: T,
+  sourceFile: string,
+): T {
+  const { isClientComponent, componentPath } =
+    detectClientComponent(sourceFile);
+
+  if (!isClientComponent) {
+    // Not a client component, return as-is
+    return Component;
+  }
+
+  // Get the component name from the file path
+  const componentName = getComponentNameFromPath(componentPath);
+
+  // Wrap for automatic hydration
+  return autoWrapClientComponent(Component, componentName) as T;
+}
+
+/**
+ * Alternative: Automatically wrap a component based on its __filename
+ *
+ * Can be used as a default export wrapper:
+ * export default autoWrapIfClient(MyComponent, __filename);
+ */
+export function autoWrapIfClient<T extends React.ComponentType<any>>(
+  Component: T,
+  filename: string,
+): T {
+  return createClientComponent(Component, filename);
+}
+
+/**
+ * Clear the component cache (useful for testing or hot reload)
+ */
+export function clearComponentCache(): void {
+  componentCache.clear();
+}

package/src/core/hydration-generator.ts

@@ -0,0 +1,94 @@
+import * as fs from "fs";
+import * as path from "path";
+import {
+  getClientComponents,
+  getComponentNameFromPath,
+} from "./component-analyzer";
+
+/**
+ * Generates separate entry point files for each client component
+ * These files will be bundled separately to reduce bundle size
+ */
+export function generateHydrationEntryFiles(
+  srcDir: string,
+  outputDir: string,
+): string[] {
+  const clientComponentPaths = getClientComponents(srcDir);
+
+  // Ensure output directory exists
+  if (!fs.existsSync(outputDir)) {
+    fs.mkdirSync(outputDir, { recursive: true });
+  }
+
+  const entryFiles: string[] = [];
+
+  for (const componentPath of clientComponentPaths) {
+    const componentName = getComponentNameFromPath(componentPath);
+    const relativePath = path.relative(srcDir, componentPath);
+
+    // Compute relative import path from assets/hydrate to the component
+    const fromAssets = path.join(outputDir, "dummy.ts");
+    let importPath = path.relative(path.dirname(fromAssets), componentPath);
+
+    // Normalize path separators to forward slashes (required for imports)
+    importPath = importPath.replace(/\\/g, "/");
+
+    // Remove .tsx/.ts extension if present and add it explicitly
+    importPath = importPath.replace(/\.tsx?$/, "");
+
+    // Create entry file for this component
+    const entryFileName = `${componentName}.ts`;
+    const entryFilePath = path.join(outputDir, entryFileName);
+
+    // Generate the entry file content
+    const entryContent = `
+import { hydrateRoot } from 'react-dom/client';
+import * as React from 'react';
+
+// Import the client component
+import ${componentName} from '${importPath}';
+
+/**
+ * Auto-generated hydration entry for ${componentName}
+ * This file is bundled separately to reduce the main bundle size
+ */
+
+// Find all instances of this component marked with data-hydration-id
+const instances = document.querySelectorAll('[data-hydration-id]');
+
+instances.forEach((element) => {
+  const hydrationId = element.getAttribute('data-hydration-id');
+  if (hydrationId) {
+    try {
+      // Hydrate the component
+      hydrateRoot(element, React.createElement(${componentName}));
+      console.log('[Hydration] Successfully hydrated ${componentName} (id: ' + hydrationId + ')');
+    } catch (error) {
+      console.error('[Hydration] Failed to hydrate ${componentName}:', error);
+    }
+  }
+});
+`.trim();
+
+    fs.writeFileSync(entryFilePath, entryContent, "utf-8");
+    entryFiles.push(entryFilePath);
+
+    console.log(`Generated hydration entry: ${entryFileName}`);
+  }
+
+  return entryFiles;
+}
+
+/**
+ * Get all hydration entry files that were generated
+ */
+export function getHydrationEntryFiles(outputDir: string): string[] {
+  if (!fs.existsSync(outputDir)) {
+    return [];
+  }
+
+  return fs
+    .readdirSync(outputDir)
+    .filter((file) => file.endsWith(".ts") && !file.endsWith(".spec.ts"))
+    .map((file) => path.join(outputDir, file));
+}

package/src/core/hydration-manifest.ts

@@ -0,0 +1,79 @@
+/**
+ * Hydration manifest loader
+ * Reads the generated hydration manifest at runtime to map component names to chunked filenames
+ */
+
+import * as fs from "fs";
+import * as path from "path";
+
+export interface HydrationManifest {
+  [componentName: string]: string; // componentName -> chunkFileName
+}
+
+let cachedManifest: HydrationManifest | null = null;
+
+/**
+ * Get the hydration manifest
+ * The manifest is generated during build and contains mappings of component names to cache-busted chunk filenames
+ */
+export function getHydrationManifest(): HydrationManifest {
+  if (cachedManifest) {
+    return cachedManifest;
+  }
+
+  // Try dist folder first (where it's generated), then legacy src location
+  const manifestPaths = [
+    path.join(process.cwd(), "dist", "hydration-manifest.json"),
+    path.join(process.cwd(), "src", "hydration-manifest.json"), // legacy fallback
+  ];
+
+  let manifestPath: string | null = null;
+  for (const p of manifestPaths) {
+    if (fs.existsSync(p)) {
+      manifestPath = p;
+      break;
+    }
+  }
+
+  if (!manifestPath) {
+    console.warn(
+      "[Hydration] Manifest file not found at any of:",
+      manifestPaths,
+      "- ensure build:hydration has been run",
+    );
+    return {};
+  }
+
+  try {
+    const content = fs.readFileSync(manifestPath, "utf-8");
+    cachedManifest = JSON.parse(content) as HydrationManifest;
+    return cachedManifest;
+  } catch (error) {
+    console.error("[Hydration] Failed to load hydration manifest:", error);
+    cachedManifest = {};
+    return cachedManifest;
+  }
+}
+
+/**
+ * Get the chunk filename for a specific component
+ */
+export function getChunkFileName(componentName: string): string | null {
+  const manifest = getHydrationManifest();
+  return manifest[componentName] || null;
+}
+
+/**
+ * Get the public path for a component chunk
+ */
+export function getChunkPath(componentName: string): string | null {
+  const fileName = getChunkFileName(componentName);
+  return fileName ? `/chunks/${fileName}` : null;
+}
+
+/**
+ * Invalidate cached manifest (useful for development mode with hot reload)
+ */
+export function invalidateManifestCache(): void {
+  cachedManifest = null;
+}