@omriashke/dynamico-core 0.1.9 → 0.1.12

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omriashke/dynamico-core",
-  "version": "0.1.9",
+  "version": "0.1.12",
   "description": "Renderer-agnostic core for dynamico: source adapters, module loader, versioned component registry.",
   "license": "Apache-2.0",
   "type": "module",
@@ -10,7 +10,14 @@
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node/index.d.ts",
+      "import": "./dist/node/index.js",
+      "default": "./dist/node/index.js"
     }
   },
   "files": [
@@ -33,17 +40,19 @@
   "publishConfig": {
     "access": "public"
   },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "dev": "tsc -p tsconfig.json -w"
+  },
   "peerDependencies": {
     "react": ">=18"
   },
   "devDependencies": {
+    "@types/node": "^22.10.0",
     "@types/react": "^18.3.0",
     "react": "^19.0.0",
     "typescript": "^5.6.3"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "dev": "tsc -p tsconfig.json -w"
   }
-}
+}

package/src/bookPreview.ts

@@ -3,6 +3,13 @@ import type { PropsSchema } from "./types.js";
 
 export type BookPreviewJson = Record<string, unknown>;
 
+/** Filenames recognized as Dynamico Book catalog configs on disk. */
+export const BOOK_CONFIG_FILENAMES = ["book.config.json", "storybook.config.json"] as const;
+
+export function isBookConfigFilename(name: string): boolean {
+  return (BOOK_CONFIG_FILENAMES as readonly string[]).includes(name);
+}
+
 export interface BookPreviewConfig {
   fixtures?: Record<string, BookPreviewJson>;
   /** Registry components wrapping every preview (outermost last). */

package/src/constants.ts

@@ -0,0 +1,9 @@
+/** Registry manifest filename at the source directory root. */
+export const MANIFEST_FILENAME = "dynamico.config.json" as const;
+
+/** Matches co-located author test files — not registry components. */
+export const COMPONENT_TEST_RE = /\.test\.(tsx|jsx|ts|js)$/;
+
+export function isComponentTestFilename(filename: string): boolean {
+  return COMPONENT_TEST_RE.test(filename);
+}

package/src/esbuildFlatten.ts

@@ -0,0 +1,47 @@
+/** Marker appended once so loadModule does not double-flatten esbuild bundles. */
+export const ESBUILD_FLATTEN_MARKER = ";// dynamico-flat-exports";
+
+export interface EsbuildExportEntry {
+  exportKey: string;
+  varName: string;
+}
+
+/** Parse esbuild `__export(mod, { name: () => var, ... })` named export entries. */
+export function parseEsbuildNamedExports(code: string): EsbuildExportEntry[] {
+  const exportBlockMatch = code.match(/__export\(\w+,\s*\{([\s\S]*?)\}\s*\)/);
+  if (!exportBlockMatch) return [];
+  const entries: EsbuildExportEntry[] = [];
+  for (const m of exportBlockMatch[1].matchAll(/(\w+):\s*\(\)\s*=>\s*(\w+)/g)) {
+    entries.push({ exportKey: m[1], varName: m[2] });
+  }
+  return entries;
+}
+
+/**
+ * Append a plain `module.exports = { ... }` assignment so Hermes and relative
+ * imports (e.g. `require("../Colors").Colors`) see named exports, not only
+ * getter-based defaults.
+ */
+export function appendPlainEsbuildExports(code: string): string {
+  if (code.includes(ESBUILD_FLATTEN_MARKER)) return code;
+
+  const entries = parseEsbuildNamedExports(code);
+  if (entries.length === 0) {
+    const defaultMatch = code.match(/default:\s*\(\)\s*=>\s*(\w+)/);
+    if (!defaultMatch) return code;
+    const fn = defaultMatch[1];
+    const propsMatch = code.match(/propsSchema:\s*\(\)\s*=>\s*(\w+)/);
+    const propsPart = propsMatch ? `,propsSchema:${propsMatch[1]}` : "";
+    return `${code}${ESBUILD_FLATTEN_MARKER}\n;(function(){try{if(typeof ${fn}==='function'){module.exports={__esModule:true,default:${fn}${propsPart}};}}catch(e){}})();\n`;
+  }
+
+  const parts = entries.map(({ exportKey, varName }) =>
+    exportKey === "default" ? `default:${varName}` : `${exportKey}:${varName}`,
+  );
+  const defaultEntry = entries.find((e) => e.exportKey === "default");
+  const guard = defaultEntry
+    ? `(typeof ${defaultEntry.varName}!=='undefined')`
+    : "true";
+
+  return `${code}${ESBUILD_FLATTEN_MARKER}\n;(function(){try{if(${guard}){module.exports={__esModule:true,${parts.join(",")}};}}catch(e){}})();\n`;
+}

package/src/index.ts

@@ -17,9 +17,14 @@ export type {
 } from "./types.js";
 
 export { Registry } from "./registry.js";
-export { loadModule } from "./loader.js";
+export { loadModule, resolveModuleDefault } from "./loader.js";
+export {
+  appendPlainEsbuildExports,
+  parseEsbuildNamedExports,
+  ESBUILD_FLATTEN_MARKER,
+} from "./esbuildFlatten.js";
 export { createRemoteSource, type RemoteSourceOptions } from "./sources/remote.js";
-export { validateProps, type PropsValidationResult } from "./propsSchema.js";
+export { validateProps, extractPropsSchema, type PropsValidationResult } from "./propsSchema.js";
 export { generateDefaultProps } from "./defaultProps.js";
 export {
   collectBookPreviewPropSets,
@@ -27,12 +32,26 @@ export {
   resolveBookFixtures,
   resolveBookPropValues,
   validateBookPreviewsForComponent,
+  BOOK_CONFIG_FILENAMES,
+  isBookConfigFilename,
   type BookPreviewBlock,
   type BookPreviewConfig,
   type BookPreviewEntry,
   type BookPreviewPropSet,
   type BookPreviewValidationResult,
 } from "./bookPreview.js";
+export {
+  resolveRelativeComponentName,
+  extractRelativeRequires,
+  collectRelativeComponentDeps,
+  validateRelativeImports,
+  type RelativeImportValidation,
+} from "./relativeRequires.js";
+export {
+  MANIFEST_FILENAME,
+  COMPONENT_TEST_RE,
+  isComponentTestFilename,
+} from "./constants.js";
 export {
   createRuntime,
   type RuntimeAPI,
@@ -40,6 +59,7 @@ export {
   type DynamicoProviderProps,
   type DynamicComponentProps,
 } from "./react/createRuntime.js";
+export { createUseRegistryModule } from "./react/useRegistryModule.js";
 export {
   createPackageScope,
   createPackageScopeFromNames,

package/src/loader.ts

@@ -1,11 +1,26 @@
 import type { Scope } from "./types.js";
+import { appendPlainEsbuildExports } from "./esbuildFlatten.js";
 
-/** esbuild CJS bundles assign exports before the component function; materialize at end. */
-function patchEsbuildDefaultExport(code: string): string {
-  const m = code.match(/default:\s*\(\)\s*=>\s*(\w+)/);
-  if (!m) return code;
-  const fn = m[1];
-  return `${code}\n;try{var __d=${fn};if(typeof __d==='function'){try{Object.defineProperty(module.exports,'default',{value:__d,enumerable:true,writable:true,configurable:true});}catch(e){module.exports.default=__d;}}}catch(e){}\n`;
+/** Copy exports to a plain object (no getters) so Hermes can read `.default` reliably. */
+function toPlainExports(exports: Record<string, unknown>): Record<string, unknown> {
+  const plain: Record<string, unknown> = {};
+  for (const key of Object.getOwnPropertyNames(exports)) {
+    const desc = Object.getOwnPropertyDescriptor(exports, key);
+    if (desc?.get && !desc.set) {
+      try {
+        const value = desc.get.call(exports);
+        if (value !== undefined) plain[key] = value;
+      } catch {
+        /* skip broken getter */
+      }
+    } else if (desc && "value" in desc) {
+      plain[key] = desc.value;
+    } else {
+      plain[key] = exports[key];
+    }
+  }
+  if (!("__esModule" in plain)) plain.__esModule = true;
+  return plain;
 }
 
 /** Replace getter-only exports with plain values (Hermes-safe). */
@@ -24,7 +39,6 @@ function materializeGetterExports(exports: Record<string, unknown>): void {
             writable: true,
           });
         } catch {
-          // Hermes may leave non-configurable getters; assign directly.
           (exports as Record<string, unknown>)[key] = value;
         }
       }
@@ -34,6 +48,25 @@ function materializeGetterExports(exports: Record<string, unknown>): void {
   }
 }
 
+/** Resolve the default export from a loaded CJS module object (Hermes-safe). */
+export function resolveModuleDefault(exp: unknown): unknown {
+  if (typeof exp === "function") return exp;
+  if (!exp || typeof exp !== "object") return undefined;
+  const exports = exp as Record<string, unknown>;
+  const desc = Object.getOwnPropertyDescriptor(exports, "default");
+  if (desc?.get && !desc.set) {
+    try {
+      const fromGetter = desc.get.call(exports);
+      if (typeof fromGetter === "function") return fromGetter;
+    } catch {
+      /* fall through */
+    }
+  }
+  const d = exports.default;
+  if (typeof d === "function") return d;
+  return undefined;
+}
+
 /**
  * Execute a CommonJS-style code string in a controlled scope.
  *
@@ -57,9 +90,6 @@ export function loadModule(
     if (name.startsWith("./") || name.startsWith("../") || name.startsWith("/")) {
       return requireRelative(name);
     }
-    // Use `in` (triggers Proxy `has` traps) so that hosts can supply scope
-    // via a Proxy and resolve module bindings lazily. Falls back to
-    // `hasOwnProperty` semantics for plain object scopes.
     if (name in scope) {
       return scope[name];
     }
@@ -68,11 +98,9 @@ export function loadModule(
     );
   };
 
-  // The compiled body is just the function body; arguments are well-known.
   // eslint-disable-next-line no-new-func
-  const fn = new Function("module", "exports", "require", patchEsbuildDefaultExport(code));
+  const fn = new Function("module", "exports", "require", appendPlainEsbuildExports(code));
   fn(moduleObj, moduleObj.exports, requireFn);
   materializeGetterExports(moduleObj.exports);
-
-  return moduleObj.exports;
+  return toPlainExports(moduleObj.exports);
 }

package/src/node/bookConfig.ts

@@ -0,0 +1,63 @@
+import { existsSync, readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  BOOK_CONFIG_FILENAMES,
+  isBookConfigFilename,
+  type BookPreviewConfig,
+} from "../bookPreview.js";
+
+export type BookConfigFilename = (typeof BOOK_CONFIG_FILENAMES)[number];
+
+export interface BookConfigFile {
+  filename: BookConfigFilename;
+  source: string;
+}
+
+export function bookConfigPathSync(dir: string): string | null {
+  for (const name of BOOK_CONFIG_FILENAMES) {
+    const filePath = join(dir, name);
+    if (existsSync(filePath)) return filePath;
+  }
+  return null;
+}
+
+export function readBookPreviewConfigSync(dir: string): BookPreviewConfig | undefined {
+  const filePath = bookConfigPathSync(dir);
+  if (!filePath) return undefined;
+  try {
+    return JSON.parse(readFileSync(filePath, "utf8")) as BookPreviewConfig;
+  } catch {
+    return undefined;
+  }
+}
+
+export async function readBookPreviewConfigAsync(dir: string): Promise<BookPreviewConfig | undefined> {
+  for (const name of BOOK_CONFIG_FILENAMES) {
+    const filePath = join(dir, name);
+    if (!existsSync(filePath)) continue;
+    try {
+      return JSON.parse(await readFile(filePath, "utf8")) as BookPreviewConfig;
+    } catch {
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+/** Raw book catalog file to ship with `dynamico push --dir`. */
+export async function readBookConfigFileAsync(dir: string): Promise<BookConfigFile | undefined> {
+  for (const filename of BOOK_CONFIG_FILENAMES) {
+    const filePath = join(dir, filename);
+    if (!existsSync(filePath)) continue;
+    const source = await readFile(filePath, "utf8");
+    JSON.parse(source);
+    return { filename, source };
+  }
+  return undefined;
+}
+
+export function isBookConfigPath(relPath: string): boolean {
+  const base = relPath.split(/[/\\]/).pop() ?? relPath;
+  return isBookConfigFilename(base);
+}

package/src/node/index.ts

@@ -0,0 +1,9 @@
+export {
+  bookConfigPathSync,
+  readBookPreviewConfigSync,
+  readBookPreviewConfigAsync,
+  readBookConfigFileAsync,
+  isBookConfigPath,
+  type BookConfigFilename,
+  type BookConfigFile,
+} from "./bookConfig.js";

package/src/packageScope.ts

@@ -1,6 +1,7 @@
 import { createElement, useSyncExternalStore, type ComponentType } from "react";
 import type { CompiledModule, Scope, Source } from "./types.js";
 import { loadModule } from "./loader.js";
+import { resolveRelativeComponentName } from "./relativeRequires.js";
 
 export interface PackageScopeOptions {
   /** Registry component names (export name = registry name). */
@@ -22,6 +23,7 @@ interface ModuleState {
   /** Bumped on every ingest so useSyncExternalStore subscribers re-render. */
   revision: number;
   listeners: Set<() => void>;
+  watchRelease?: () => void;
 }
 
 /**
@@ -52,9 +54,17 @@ export function createPackageScope(
 
   const subscribe = (name: string, listener: () => void): (() => void) => {
     const state = getState(name);
+    const wasEmpty = state.listeners.size === 0;
     state.listeners.add(listener);
+    if (wasEmpty && source.watch) {
+      state.watchRelease = source.watch(name);
+    }
     return () => {
       state.listeners.delete(listener);
+      if (state.listeners.size === 0) {
+        state.watchRelease?.();
+        state.watchRelease = undefined;
+      }
     };
   };
 
@@ -74,11 +84,7 @@ export function createPackageScope(
   let makeLazy: (name: string) => LazyComponent;
 
   const requireRelative = (specifier: string): unknown => {
-    const base = specifier
-      .replace(/^\.+\//, "")
-      .replace(/\.[tj]sx?$/, "")
-      .split("/")
-      .pop();
+    const base = resolveRelativeComponentName(specifier);
     if (!base) throw new Error(`dynamico: cannot resolve '${specifier}'`);
     ensureLoaded(base);
     const dep = modules.get(base)?.factory;
@@ -128,14 +134,16 @@ export function createPackageScope(
   };
 
   source.subscribe(({ module }) => {
-    if (componentSet.has(module.name)) {
+    if (!componentSet.has(module.name)) return;
+    const state = getState(module.name);
+    if (state.factory !== undefined || state.listeners.size > 0 || state.loading) {
       ingest(module.name, module);
     }
   });
 
   makeLazy = (name: string): LazyComponent => {
-    ensureLoaded(name);
     const Lazy: LazyComponent = (props) => {
+      ensureLoaded(name);
       const revision = useSyncExternalStore(
         (cb) => subscribe(name, cb),
         () => getRevision(name),

package/src/propsSchema.ts

@@ -43,3 +43,38 @@ function describe(v: unknown): string {
   if (typeof v === "function") return "function";
   return typeof v;
 }
+
+/** Parse `export const propsSchema = { … }` from component source text. */
+export function extractPropsSchema(source: string): PropsSchema | undefined {
+  const marker = "export const propsSchema";
+  const idx = source.indexOf(marker);
+  if (idx < 0) return undefined;
+
+  const after = source.slice(idx + marker.length);
+  const eq = after.indexOf("=");
+  if (eq < 0) return undefined;
+
+  let rest = after.slice(eq + 1).trimStart();
+  if (!rest.startsWith("{")) return undefined;
+
+  let depth = 0;
+  let end = 0;
+  for (let i = 0; i < rest.length; i++) {
+    const ch = rest[i];
+    if (ch === "{") depth++;
+    else if (ch === "}") {
+      depth--;
+      if (depth === 0) {
+        end = i + 1;
+        break;
+      }
+    }
+  }
+  if (end === 0) return undefined;
+
+  try {
+    return new Function(`return (${rest.slice(0, end)})`)() as PropsSchema;
+  } catch {
+    return undefined;
+  }
+}

package/src/react/createRuntime.tsx

@@ -1,5 +1,6 @@
 import * as React from "react";
 import { Registry } from "../registry.js";
+import { resolveModuleDefault } from "../loader.js";
 import type {
   ComponentFactory,
   DynamicError,
@@ -187,22 +188,8 @@ export function createRuntime(
 }
 
 function pickDefault(factory: ComponentFactory): unknown {
-  if (typeof factory === "function") return factory;
-  if (!factory || typeof factory !== "object") return undefined;
-  if ("default" in factory) {
-    const desc = Object.getOwnPropertyDescriptor(factory, "default");
-    if (desc?.get && !desc.set) {
-      try {
-        const fromGetter = desc.get.call(factory);
-        if (typeof fromGetter === "function") return fromGetter;
-      } catch {
-        /* fall through */
-      }
-    }
-    const d = factory.default;
-    if (typeof d === "function") return d;
-  }
-  return undefined;
+  const d = resolveModuleDefault(factory);
+  return typeof d === "function" ? d : undefined;
 }
 
 function defaultErrorView(error: DynamicError): React.ReactElement {

package/src/react/useRegistryModule.ts

@@ -0,0 +1,15 @@
+import { useSyncExternalStore } from "react";
+import type { RegistryModuleSubscription } from "../registryModule.js";
+
+/** React hook factory — re-renders when a registry data module (e.g. Colors) is pushed. */
+export function createUseRegistryModule<T extends Record<string, unknown>>(
+  subscription: RegistryModuleSubscription<T>,
+): () => T {
+  return function useRegistryModule() {
+    return useSyncExternalStore(
+      subscription.subscribe,
+      subscription.getSnapshot,
+      subscription.getSnapshot,
+    );
+  };
+}

package/src/registry.ts

@@ -23,16 +23,38 @@ export class Registry {
   private listeners = new Map<string, Set<RegistryListener>>();
   private anyListeners = new Set<RegistryListener>();
   private inflight = new Map<string, Promise<RegistryEntry>>();
+  /** WS push cache — modules are ingested only when ensure() or a subscriber asks. */
+  private moduleCache = new Map<string, import("./types.js").CompiledModule>();
+  private watchReleases = new Map<string, () => void>();
 
   constructor(
     private readonly source: Source,
     private scope: Scope,
   ) {
     this.source.subscribe(({ module }) => {
-      void this.ingestAsync(module.name, module);
+      if (module.removed) {
+        this.moduleCache.delete(module.name);
+        if (this.entries.has(module.name) || (this.listeners.get(module.name)?.size ?? 0) > 0) {
+          void this.ingestAsync(module.name, module);
+        }
+        return;
+      }
+      this.moduleCache.set(module.name, module);
+      if (this.shouldIngestOnPush(module.name)) {
+        void this.ingestAsync(module.name, module);
+      }
     });
   }
 
+  /** Re-ingest a WS push when the component is already loaded or has active subscribers. */
+  private shouldIngestOnPush(name: string): boolean {
+    return (
+      this.entries.has(name) ||
+      (this.listeners.get(name)?.size ?? 0) > 0 ||
+      this.inflight.has(name)
+    );
+  }
+
   /** Replace or extend the current scope (rare; typically set once). */
   setScope(scope: Scope): void {
     this.scope = scope;
@@ -61,8 +83,8 @@ export class Registry {
     if (existing) return existing;
     const pending = this.inflight.get(name);
     if (pending) return pending;
-    const p = this.source
-      .fetch(name)
+    const cached = this.moduleCache.get(name);
+    const p = (cached ? Promise.resolve(cached) : this.source.fetch(name))
       .then((module) => this.ingestAsync(name, module))
       .finally(() => {
         this.inflight.delete(name);
@@ -78,10 +100,23 @@ export class Registry {
       set = new Set();
       this.listeners.set(name, set);
     }
+    const wasEmpty = set.size === 0;
     set.add(listener);
+    if (wasEmpty && this.source.watch) {
+      this.watchReleases.set(name, this.source.watch(name));
+    }
+    const cached = this.moduleCache.get(name);
+    if (cached && !this.entries.has(name) && !this.inflight.has(name)) {
+      void this.ingestAsync(name, cached);
+    }
     return () => {
       set!.delete(listener);
-      if (set!.size === 0) this.listeners.delete(name);
+      if (set!.size === 0) {
+        this.listeners.delete(name);
+        const release = this.watchReleases.get(name);
+        release?.();
+        this.watchReleases.delete(name);
+      }
     };
   }
 
@@ -148,7 +183,10 @@ export class Registry {
       get(target, prop) {
         if (typeof prop !== "string") return undefined;
         const resolved = registry.resolveExport(name, prop);
-        if (resolved !== undefined) return resolved;
+        if (resolved !== undefined) {
+          delete target[prop];
+          return resolved;
+        }
         if (prop in target) return target[prop];
         const c = make(prop);
         target[prop] = c;
@@ -163,11 +201,26 @@ export class Registry {
   /**
    * Take a CompiledModule from the source, evaluate it (or record a compile
    * error), update the entry, and notify listeners.
+   *
+   * Same-version deduplication: if the current entry already carries this
+   * exact version (and has no error), skip re-evaluation entirely. This is the
+   * primary guard against the WebSocket connect-replay pattern where the server
+   * immediately pushes the current module for every watched component on every
+   * (re)connect — without this, each push produces a brand-new JS function
+   * object and React unmounts+remounts the entire component tree even though
+   * nothing changed, causing visible flicker and lost interaction state.
    */
   private async ingestAsync(
     name: string,
     module: import("./types.js").CompiledModule,
   ): Promise<RegistryEntry> {
+    if (!module.removed && !module.error) {
+      const current = this.entries.get(name);
+      if (current && !current.error && current.version === module.version) {
+        return current;
+      }
+    }
+
     if (module.removed) {
       this.entries.delete(name);
       this.lazyProxies.delete(name);

package/src/registryModule.ts

@@ -43,6 +43,7 @@ export function createRegistryModuleSubscription<T extends Record<string, unknow
 ): RegistryModuleSubscription<T> {
   let snapshot = { ...defaults } as T;
   const listeners = new Set<() => void>();
+  let watchRelease: (() => void) | undefined;
 
   const notify = () => {
     for (const listener of listeners) listener();
@@ -83,12 +84,20 @@ export function createRegistryModuleSubscription<T extends Record<string, unknow
     }
   });
 
-  void reload();
-
   return {
     subscribe(listener) {
       listeners.add(listener);
-      return () => listeners.delete(listener);
+      if (listeners.size === 1) {
+        if (source.watch) watchRelease = source.watch(name);
+        void reload();
+      }
+      return () => {
+        listeners.delete(listener);
+        if (listeners.size === 0) {
+          watchRelease?.();
+          watchRelease = undefined;
+        }
+      };
     },
     getSnapshot: () => snapshot,
     proxy,