@omriashke/dynamico-core 0.1.8 → 0.1.11

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{if(typeof ${fn}==='function'){module.exports.default=${fn};}}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). */
@@ -16,12 +31,16 @@ function materializeGetterExports(exports: Record<string, unknown>): void {
     try {
       const value = desc.get.call(exports);
       if (value !== undefined) {
-        Object.defineProperty(exports, key, {
-          value,
-          enumerable: true,
-          configurable: true,
-          writable: true,
-        });
+        try {
+          Object.defineProperty(exports, key, {
+            value,
+            enumerable: true,
+            configurable: true,
+            writable: true,
+          });
+        } catch {
+          (exports as Record<string, unknown>)[key] = value;
+        }
       }
     } catch {
       /* leave getter */
@@ -29,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.
  *
@@ -52,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];
     }
@@ -63,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,16 +188,8 @@ export function createRuntime(
 }
 
 function pickDefault(factory: ComponentFactory): unknown {
-  if (factory && typeof factory === "object") {
-    if ("default" in factory) {
-      const d = factory.default;
-      if (typeof d === "function") return d;
-    }
-    // CommonJS interop: the value itself may be the component
-    if (typeof factory === "function") return factory;
-  }
-  if (typeof factory === "function") return factory;
-  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);
+      }
     };
   }
 

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,

package/src/relativeRequires.ts

@@ -1,3 +1,5 @@
+import type { Diagnostic } from "./types.js";
+
 /** Map a relative require specifier to the flat registry component name (basename). */
 export function resolveRelativeComponentName(specifier: string): string | null {
   if (!specifier.startsWith("./") && !specifier.startsWith("../") && !specifier.startsWith("/")) {
@@ -37,3 +39,49 @@ export function collectRelativeComponentDeps(code: string, componentName?: strin
   }
   return [...deps];
 }
+
+export interface RelativeImportValidation {
+  ok: boolean;
+  message?: string;
+  diagnostics?: Diagnostic[];
+}
+
+/**
+ * Reject relative imports that resolve to registry names not in the manifest.
+ * Local utility files should be bundled at compile time; any remaining relative
+ * require() must target another registered component.
+ */
+export function validateRelativeImports(
+  code: string,
+  registered: ReadonlySet<string>,
+  componentName?: string,
+): RelativeImportValidation {
+  const unresolved: string[] = [];
+  for (const specifier of extractRelativeRequires(code)) {
+    const base = resolveRelativeComponentName(specifier);
+    if (!base) continue;
+    if (base === componentName) continue;
+    if (!registered.has(base)) unresolved.push(specifier);
+  }
+  if (unresolved.length === 0) return { ok: true };
+
+  const lines = unresolved.map(
+    (spec) =>
+      `  ${spec} → registry component '${resolveRelativeComponentName(spec)}' is not registered`,
+  );
+  const message =
+    `relative import(s) must target a registered component or a local file bundled into this module:\n` +
+    `${lines.join("\n")}\n` +
+    `Push the dependency as its own component, move helpers into this file, ` +
+    `import from host scope (e.g. @newscast/utils-app-ui), or colocate as ./sibling.ts (auto-bundled).`;
+
+  return {
+    ok: false,
+    message,
+    diagnostics: unresolved.map((spec) => ({
+      severity: "error" as const,
+      message: `unregistered relative import '${spec}'`,
+      code: "RELATIVE_IMPORT",
+    })),
+  };
+}