@soederpop/luca 0.0.3 → 0.0.4

package/src/client.ts

@@ -38,6 +38,9 @@ export class Client<
   static override optionsSchema = ClientOptionsSchema
   static override eventsSchema = ClientEventsSchema
 
+  /** Self-register a Client subclass from a static initialization block. */
+  static register: (SubClass: typeof Client, id?: string) => typeof Client
+
   static attach(container: Container & ClientsInterface): any {
     Object.assign(container, {
       get clients() {
@@ -100,6 +103,61 @@ export class Client<
   }
 }
 
+// --- Registry and Client.register must be defined BEFORE subclasses ---
+// because static blocks in RestClient/GraphClient/WebSocketClient run at class declaration time.
+
+export class ClientsRegistry extends Registry<Client<any>> {
+  override scope = "clients"
+  override baseClass = Client
+}
+
+export const clients = new ClientsRegistry();
+
+export const helperCache = new Map();
+
+/**
+ * Self-register a Client subclass from a static initialization block.
+ * IMPORTANT: Place the static block AFTER all static override declarations
+ * so schemas, envVars, and other metadata are set before interceptRegistration fires.
+ *
+ * @example
+ * ```typescript
+ * export class OpenAIClient extends Client {
+ *   static override stateSchema = OpenAIClientStateSchema
+ *   static override optionsSchema = OpenAIClientOptionsSchema
+ *   static { Client.register(this, 'openai') }  // must come last
+ * }
+ * ```
+ */
+Client.register = function registerClient(
+  SubClass: typeof Client,
+  id?: string,
+) {
+  const registryId = id ?? SubClass.name[0]!.toLowerCase() + SubClass.name.slice(1)
+
+  // Auto-set shortcut if not explicitly overridden on this class
+  if (!Object.getOwnPropertyDescriptor(SubClass, 'shortcut')?.value ||
+      (SubClass as any).shortcut === 'unspecified' ||
+      (SubClass as any).shortcut === 'clients.base') {
+    ;(SubClass as any).shortcut = `clients.${registryId}` as const
+  }
+
+  // Register in the clients registry (interceptRegistration sees all statics above)
+  clients.register(registryId, SubClass as any)
+
+  // Generate default attach() if not explicitly overridden on this class
+  if (!Object.getOwnPropertyDescriptor(SubClass, 'attach')) {
+    ;(SubClass as any).attach = (container: any) => {
+      clients.register(registryId, SubClass as any)
+      return container
+    }
+  }
+
+  return SubClass
+}
+
+// --- Built-in client subclasses ---
+
 export class RestClient<
   T extends ClientState = ClientState,
   K extends ClientOptions = ClientOptions
@@ -107,18 +165,15 @@ export class RestClient<
   axios!: AxiosInstance;
 
   static override shortcut: string = "clients.rest"
-
-  static override attach(container: Container & ClientsInterface): any {
-    return container
-  }
+  static { Client.register(this, 'rest') }
 
   constructor(options: K, context: ContainerContext) {
     super(options, context);
 
     this.axios = axios.create({
-      baseURL: this.baseURL, 
+      baseURL: this.baseURL,
     });
-    
+
     if (this.useJSON) {
       this.axios.defaults.headers.common = {
         ...this.axios.defaults.headers.common,
@@ -127,16 +182,16 @@ export class RestClient<
       }
     }
   }
-  
+
   async beforeRequest() {
   }
- 
+
   get useJSON() {
     return !!this.options.json
   }
-  
+
   override get baseURL() {
-    return this.options.baseURL || '/'  
+    return this.options.baseURL || '/'
   }
 
   async patch(url: string, data: any = {}, options: AxiosRequestConfig = {}) {
@@ -156,7 +211,7 @@ export class RestClient<
         }
       });
   }
- 
+
   async put(url: string, data: any = {}, options: AxiosRequestConfig = {}) {
     await this.beforeRequest();
     return this.axios({
@@ -174,7 +229,7 @@ export class RestClient<
         }
       });
   }
- 
+
   async post(url: string, data: any = {}, options: AxiosRequestConfig = {}) {
     await this.beforeRequest();
     return this.axios({
@@ -249,6 +304,7 @@ export class GraphClient<
   static override shortcut = "clients.graph" as const
   static override optionsSchema = GraphClientOptionsSchema
   static override eventsSchema = GraphClientEventsSchema
+  static { Client.register(this, 'graph') }
 
   /** The GraphQL endpoint path. Defaults to '/graphql'. */
   get endpoint() {
@@ -321,6 +377,7 @@ export class WebSocketClient<
   static override stateSchema = WebSocketClientStateSchema
   static override optionsSchema = WebSocketClientOptionsSchema
   static override eventsSchema = WebSocketClientEventsSchema
+  static { Client.register(this, 'websocket') }
 
   constructor(options?: K, context?: ContainerContext) {
     super(options, context)
@@ -444,18 +501,4 @@ export class WebSocketClient<
   }
 }
 
-
-export class ClientsRegistry extends Registry<Client<any>> {
-  override scope = "clients"
-  override baseClass = Client
-}
-
-export const clients = new ClientsRegistry();
-
-clients.register("rest", RestClient);
-clients.register("graph", GraphClient);
-clients.register("websocket", WebSocketClient);
-
-export const helperCache = new Map();
-
 export default Client;

package/src/clients/civitai/index.ts

@@ -1,10 +1,9 @@
 import {
   Client,
   type ClientOptions,
-  type ClientsInterface,
   RestClient,
 } from "@soederpop/luca/client";
-import { Container, type ContainerContext } from "@soederpop/luca/container";
+import { type ContainerContext } from "@soederpop/luca/container";
 import { isEmpty, maxBy, omitBy } from "lodash-es";
 import { NodeContainer } from "@soederpop/luca/node/container";
 import { z } from 'zod'
@@ -38,11 +37,8 @@ export type CivitaiClientState = z.infer<typeof CivitaiClientStateSchema>
  */
 export class CivitaiClient<T extends CivitaiClientState> extends RestClient<T> {
   static override stateSchema = CivitaiClientStateSchema;
-  // @ts-ignore
-  static attach(container: Container & ClientsInterface, options?: any) {
-    container.clients.register("civitai", CivitaiClient);
-    return container
-  }
+
+  static { Client.register(this, 'civitai') }
 
   constructor(options: ClientOptions, context: ContainerContext) {
     options = {

package/src/clients/comfyui/index.ts

@@ -1,9 +1,8 @@
 import {
-  type ClientsInterface,
-  clients,
+  Client,
   RestClient,
 } from "@soederpop/luca/client";
-import type { Container, ContainerContext } from "@soederpop/luca/container";
+import type { ContainerContext } from "@soederpop/luca/container";
 import { z } from 'zod'
 import { ClientStateSchema, ClientOptionsSchema } from '@soederpop/luca/schemas/base.js'
 
@@ -68,12 +67,9 @@ export class ComfyUIClient extends RestClient<ComfyUIClientState, ComfyUIClientO
   static override stateSchema = ComfyUIClientStateSchema;
   static override optionsSchema = ComfyUIClientOptionsSchema;
 
-  private ws: WebSocket | null = null;
+  static { Client.register(this, 'comfyui') }
 
-  static override attach(container: Container & ClientsInterface, options?: any) {
-    container.clients.register("comfyui", ComfyUIClient);
-    return container;
-  }
+  private ws: WebSocket | null = null;
 
   constructor(options: ComfyUIClientOptions, context: ContainerContext) {
     super(
@@ -594,4 +590,4 @@ export class ComfyUIClient extends RestClient<ComfyUIClientState, ComfyUIClientO
   }
 }
 
-export default clients.register("comfyui", ComfyUIClient);
+export default ComfyUIClient;

package/src/clients/elevenlabs/index.ts

@@ -1,8 +1,7 @@
 import { z } from 'zod'
 import { ClientStateSchema, ClientOptionsSchema, ClientEventsSchema } from '@soederpop/luca/schemas/base.js'
-import { clients, RestClient } from "@soederpop/luca/client";
-import type { Container, ContainerContext } from "@soederpop/luca/container";
-import type { ClientsInterface, ClientOptions } from "@soederpop/luca/client";
+import { Client, RestClient } from "@soederpop/luca/client";
+import type { ContainerContext } from "@soederpop/luca/container";
 import type { AxiosRequestConfig } from 'axios'
 
 declare module "@soederpop/luca/client" {
@@ -48,6 +47,7 @@ export type SynthesizeOptions = {
   modelId?: string
   outputFormat?: string
   voiceSettings?: ElevenLabsVoiceSettings
+  disableCache?: boolean
 }
 
 /**
@@ -72,11 +72,7 @@ export class ElevenLabsClient extends RestClient<ElevenLabsClientState, ElevenLa
   static override optionsSchema = ElevenLabsClientOptionsSchema
   static override eventsSchema = ElevenLabsClientEventsSchema
 
-  // @ts-ignore
-  static override attach(container: Container & ClientsInterface, options?: any) {
-    container.clients.register("elevenlabs", ElevenLabsClient);
-    return container
-  }
+  static { Client.register(this, 'elevenlabs') }
 
   override get initialState(): ElevenLabsClientState {
     return {
@@ -238,8 +234,40 @@ export class ElevenLabsClient extends RestClient<ElevenLabsClientState, ElevenLa
       }
     }
 
-    this.trackRequest(text.length)
+    // Check disk cache for previously synthesized audio
+    if (!options.disableCache) {
+      const { hashObject } = this.container.utils
+      const cacheKey = `elevenlabs:${hashObject({ text, voiceId, modelId, outputFormat, voiceSettings: options.voiceSettings })}`
+      const diskCache = this.container.feature('diskCache')
+
+      if (await diskCache.has(cacheKey)) {
+	console.log(`Cache Hit: ${cacheKey}`)
+        const cached = await diskCache.get(cacheKey)
+        const audioBuffer = Buffer.from(cached, 'base64')
+
+        this.emit('speech', {
+          voiceId,
+          text,
+          audioSize: audioBuffer.length,
+        })
+
+        return audioBuffer
+      }
+
+      const audioBuffer = await this.fetchSpeech(voiceId, outputFormat, body, text.length)
+      await diskCache.set(cacheKey, audioBuffer.toString('base64'))
+
+      this.emit('speech', { voiceId, text, audioSize: audioBuffer.length })
+      return audioBuffer
+    }
+
+    const audioBuffer = await this.fetchSpeech(voiceId, outputFormat, body, text.length)
+    this.emit('speech', { voiceId, text, audioSize: audioBuffer.length })
+    return audioBuffer
+  }
 
+  private async fetchSpeech(voiceId: string, outputFormat: string, body: Record<string, any>, charCount: number): Promise<Buffer> {
+    this.trackRequest(charCount)
     await this.beforeRequest()
 
     const response = await this.axios({
@@ -254,15 +282,7 @@ export class ElevenLabsClient extends RestClient<ElevenLabsClientState, ElevenLa
       },
     })
 
-    const audioBuffer = Buffer.from(response.data)
-
-    this.emit('speech', {
-      voiceId,
-      text,
-      audioSize: audioBuffer.length,
-    })
-
-    return audioBuffer
+    return Buffer.from(response.data)
   }
 
   /**
@@ -287,5 +307,5 @@ export class ElevenLabsClient extends RestClient<ElevenLabsClientState, ElevenLa
   }
 }
 
-export default clients.register("elevenlabs", ElevenLabsClient)
+export default ElevenLabsClient
 

package/src/clients/openai/index.ts

@@ -1,8 +1,8 @@
 import { z } from 'zod'
 import { ClientStateSchema, ClientOptionsSchema } from '@soederpop/luca/schemas/base.js'
-import { clients, Client } from "@soederpop/luca/client";
+import { Client } from "@soederpop/luca/client";
 import type { Container, ContainerContext } from "@soederpop/luca/container";
-import type { ClientsInterface } from "@soederpop/luca/client";
+
 import OpenAI from "openai";
 
 export const OpenAIClientStateSchema = ClientStateSchema.extend({
@@ -48,9 +48,7 @@ export class OpenAIClient extends Client<OpenAIClientState, OpenAIClientOptions>
   static override stateSchema = OpenAIClientStateSchema
   static override optionsSchema = OpenAIClientOptionsSchema
 
-  static override attach(container: Container & ClientsInterface): any {
-    return container;
-  }
+  static { Client.register(this, 'openai') }
 
   /** Initial state with zeroed token usage counters. */
   override get initialState(): OpenAIClientState {
@@ -446,6 +444,4 @@ export class OpenAIClient extends Client<OpenAIClientState, OpenAIClientOptions>
   }
 }
 
-clients.register("openai", OpenAIClient)
-
 export default OpenAIClient;

package/src/clients/supabase/index.ts

@@ -1,10 +1,7 @@
 import {
   Client,
-  type ClientOptions,
-  type ClientsInterface,
-  clients,
 } from "@soederpop/luca/client";
-import type { Container, ContainerContext } from "@soederpop/luca/container";
+import type { ContainerContext } from "@soederpop/luca/container";
 import { z } from "zod";
 import {
   ClientStateSchema,
@@ -141,16 +138,11 @@ export class SupabaseClient extends Client<
   static override optionsSchema = SupabaseClientOptionsSchema;
   static override eventsSchema = SupabaseClientEventsSchema;
 
+  static { Client.register(this, 'supabase') }
+
   private _sdk!: SupabaseSDKClient<any, any>;
   private _channels = new Map<string, RealtimeChannel>();
 
-  // @ts-ignore - required options (supabaseUrl, supabaseKey) widen beyond base ClientOptions
-  static attach(container: Container & ClientsInterface, options?: any) {
-    // @ts-ignore
-    container.clients.register("supabase", SupabaseClient);
-    return container;
-  }
-
   constructor(options: SupabaseClientOptions, context: ContainerContext) {
     super(options, context);
 
@@ -362,5 +354,4 @@ export class SupabaseClient extends Client<
   }
 }
 
-// @ts-ignore
-clients.register("supabase", SupabaseClient);
+export default SupabaseClient;

package/src/commands/console.ts

@@ -63,9 +63,6 @@ async function evalBeforeRepl(evalArg: string, container: any, featureContext: R
 					code = transformed
 				}
 
-				const hasTopLevelAwait = /\bawait\b/.test(code)
-				code = hasTopLevelAwait ? `(async function() { ${code} })()` : code
-
 				await vm.run(code, shared)
 				Object.assign(shared, container.context)
 			} else {

package/src/commands/eval.ts

@@ -34,7 +34,7 @@ export default async function evalCommand(options: z.infer<typeof argsSchema>, c
 	const vm = container.feature('vm')
 
 	// HACK
-	Array(container.argv.enable).map((id) => {
+	Array(container.argv.enable).filter(Boolean).map((id) => {
 		container.feature(id, { ...container.argv, enable: true }).enable()
 	})
 

package/src/commands/index.ts

@@ -12,3 +12,4 @@ import './describe.js'
 import './eval.js'
 import './help.js'
 import './scaffold.js'
+import './introspect.js'

package/src/commands/introspect.ts

@@ -0,0 +1,128 @@
+import { z } from 'zod'
+import { commands } from '../command.js'
+import { CommandOptionsSchema } from '../schemas/base.js'
+import type { ContainerContext } from '../container.js'
+import '../introspection/scan.js'
+
+declare module '../command.js' {
+	interface AvailableCommands {
+		introspect: ReturnType<typeof commands.registerHandler>
+	}
+}
+
+export const argsSchema = CommandOptionsSchema.extend({
+	src: z.array(z.string()).optional().describe('Source directories to scan (default: auto-discover features/, clients/, servers/)'),
+	output: z.string().optional().describe('Output file path (default: features/introspection.generated.ts)'),
+	'dry-run': z.boolean().default(false).describe('Preview without writing'),
+	'include-private': z.boolean().default(false).describe('Include private methods in output'),
+})
+
+async function introspect(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+	const container = context.container as any
+	const { fs, paths } = container
+
+	// Detect if we're inside the luca library itself
+	const cwd = paths.cwd
+	const isLucaLibrary = fs.exists(paths.resolve('src/introspection/scan.ts'))
+
+	if (isLucaLibrary) {
+		// Inside luca itself — delegate to the multi-target update-introspection behavior
+		const { NodeContainer } = await import('../node/container.js')
+		const lucaContainer = new NodeContainer()
+
+		const targets = [
+			{
+				name: 'node',
+				src: ['src/node/features', 'src/servers', 'src/container.ts', 'src/node/container.ts'],
+				outputPath: 'src/introspection/generated.node.ts',
+			},
+			{
+				name: 'web',
+				src: ['src/web/features', 'src/container.ts', 'src/web/container.ts'],
+				outputPath: 'src/introspection/generated.web.ts',
+			},
+			{
+				name: 'agi',
+				src: ['src/node/features', 'src/servers', 'src/agi/features', 'src/container.ts', 'src/node/container.ts', 'src/agi/container.server.ts'],
+				outputPath: 'src/introspection/generated.agi.ts',
+			},
+		]
+
+		for (const target of targets) {
+			console.log(`\nGenerating ${target.name} introspection data...`)
+			console.log(`  Sources: ${target.src.join(', ')}`)
+			console.log(`  Output: ${target.outputPath}`)
+
+			const scanner = lucaContainer.feature('introspectionScanner', {
+				src: target.src,
+				outputPath: options['dry-run'] ? undefined : target.outputPath,
+				includePrivate: options['include-private'],
+			})
+
+			scanner.on('scanCompleted', (data: any) => {
+				console.log(`  Found ${data.results} helpers in ${data.files} files (${data.duration}ms)`)
+			})
+
+			await scanner.scan()
+			const script = await scanner.generateRegistryScript()
+
+			if (options['dry-run']) {
+				console.log(`\n--- ${target.outputPath} (dry run) ---`)
+				console.log(script.slice(0, 500) + (script.length > 500 ? '\n...' : ''))
+			} else {
+				console.log(`  Wrote ${target.outputPath}`)
+			}
+		}
+
+		console.log('\nAll introspection data generated.')
+		return
+	}
+
+	// Project-local mode: auto-discover source directories
+	const defaultSrc = ['features', 'clients', 'servers']
+		.filter(dir => fs.exists(paths.resolve(dir)))
+
+	// Also scan container.ts if it exists at project root
+	const containerFile = paths.resolve('container.ts')
+	if (fs.exists(containerFile)) defaultSrc.push('container.ts')
+
+	const src = options.src || defaultSrc
+
+	if (src.length === 0) {
+		console.log('No source directories found to scan. Use --src to specify directories.')
+		return
+	}
+
+	const outputPath = options.output || 'features/introspection.generated.ts'
+	const importSource = '@soederpop/luca/introspection'
+
+	console.log(`Scanning: ${src.join(', ')}`)
+	console.log(`Output: ${outputPath}`)
+
+	const scanner = container.feature('introspectionScanner', {
+		src,
+		outputPath: options['dry-run'] ? undefined : outputPath,
+		includePrivate: options['include-private'],
+		importSource,
+	})
+
+	scanner.on('scanCompleted', (data: any) => {
+		console.log(`Found ${data.results} helpers in ${data.files} files (${data.duration}ms)`)
+	})
+
+	await scanner.scan()
+	const script = await scanner.generateRegistryScript()
+
+	if (options['dry-run']) {
+		console.log(`\n--- ${outputPath} (dry run) ---`)
+		console.log(script)
+	} else {
+		console.log(`Wrote ${outputPath}`)
+	}
+}
+
+commands.registerHandler('introspect', {
+	description: 'Generate introspection metadata from source. Works in any luca project.',
+	argsSchema,
+	handler: introspect,
+})

package/src/commands/prompt.ts

@@ -628,10 +628,7 @@ async function executePromptFile(resolvedPath: string, container: any): Promise<
 				code = transformed
 			}
 
-			const hasTopLevelAwait = /\bawait\b/.test(code)
-			if (hasTopLevelAwait) code = `(async function() { ${code} })()`
-
-			await vm.run(code, shared)
+				await vm.run(code, shared)
 			Object.assign(shared, container.context)
 
 			if (capturedLines.length) {

package/src/commands/run.ts

@@ -96,12 +96,7 @@ async function runMarkdown(scriptPath: string, options: z.infer<typeof argsSchem
 		const keysBefore = new Set(Object.keys(shared))
 		const { code: transformed } = esbuild.transformSync(source, { loader: 'tsx', format: 'cjs' })
 
-		const hasTopLevelAwait = /\bawait\b/.test(transformed)
-		const wrapped = hasTopLevelAwait
-			? `(async function() { ${transformed} })()`
-			: transformed
-
-		await vm.run(wrapped, shared)
+		await vm.run(transformed, shared)
 
 		// auto-register any new functions as blocks
 		for (const key of Object.keys(shared)) {
@@ -165,11 +160,6 @@ async function runMarkdown(scriptPath: string, options: z.infer<typeof argsSchem
 				code = transformed
 			}
 
-			const hasTopLevelAwait = /\bawait\b/.test(code)
-			code = hasTopLevelAwait
-				? `(async function() { ${code} })()`
-				: code
-
 			await vm.run(code, shared)
 
 			// if we enabled any features, they will be in the context object
@@ -186,13 +176,16 @@ async function runMarkdown(scriptPath: string, options: z.infer<typeof argsSchem
 async function runScript(scriptPath: string, context: ContainerContext) {
 	const container = context.container as any
 
-	const { exitCode, stderr } = await container.proc.runScript(scriptPath)
+	const { exitCode, stderr } = await container.proc.execAndCapture(`bun run ${scriptPath}`, {
+		onOutput: (data: string) => process.stdout.write(data),
+		onError: (data: string) => process.stderr.write(data),
+	})
 
 	if (exitCode === 0) return
 
 	console.error(`\nScript failed with exit code ${exitCode}.\n`)
 	if (stderr.length) {
-		console.error(stderr.join('\n'))
+		console.error(stderr)
 	}
 }
 

package/src/commands/sandbox-mcp.ts

@@ -154,19 +154,7 @@ export default async function mcpSandbox(options: z.infer<typeof argsSchema>, co
 		}),
 		handler: async (args) => {
 			try {
-				// Wrap code containing top-level await in an async IIFE so the VM can handle it.
-				// Try to return the last expression's value by prepending `return` to the last statement.
-				let code = args.code
-				if (/\bawait\b/.test(code) && !/^\s*\(?\s*async\b/.test(code)) {
-					const lines = code.split('\n')
-					const lastLine = lines[lines.length - 1]
-					// If the last line doesn't start with a keyword that can't be returned, add return
-					if (!/^\s*(var|let|const|if|for|while|switch|try|throw|class|function)\b/.test(lastLine)) {
-						lines[lines.length - 1] = `return ${lastLine}`
-					}
-					code = `(async () => { ${lines.join('\n')} })()`
-				}
-				const result = await vmFeature.run(code, sandboxContext)
+				const result = await vmFeature.run(args.code, sandboxContext)
 
 				let text: string
 				if (result === undefined) {

package/src/feature.ts

@@ -22,6 +22,9 @@ export abstract class Feature<T extends FeatureState = FeatureState, K extends F
     static override optionsSchema = FeatureOptionsSchema
     static override eventsSchema = FeatureEventsSchema
 
+    /** Self-register a Feature subclass from a static initialization block. */
+    static register: (SubClass: typeof Feature, id?: string) => typeof Feature
+
     get shortcut() {
         return (this.constructor as any).shortcut as string
     }
@@ -67,9 +70,49 @@ export abstract class Feature<T extends FeatureState = FeatureState, K extends F
     }
 }
 
-export class FeaturesRegistry extends Registry<Feature<any, any>> { 
+export class FeaturesRegistry extends Registry<Feature<any, any>> {
     override scope = "features"
     override baseClass = Feature as any
 }
 
-export const features = new FeaturesRegistry()
+export const features = new FeaturesRegistry()
+
+/**
+ * Self-register a Feature subclass from a static initialization block.
+ * IMPORTANT: Place the static block AFTER all static override declarations
+ * so schemas, envVars, and other metadata are set before interceptRegistration fires.
+ *
+ * @example
+ * ```typescript
+ * export default class DNS extends Feature<DnsState, DnsOptions> {
+ *   static override stateSchema = DnsStateSchema
+ *   static override optionsSchema = DnsOptionsSchema
+ *   static { Feature.register(this, 'dns') }  // must come last
+ * }
+ * ```
+ */
+Feature.register = function registerFeature(
+  SubClass: typeof Feature,
+  id?: string,
+) {
+  const registryId = id ?? SubClass.name[0]!.toLowerCase() + SubClass.name.slice(1)
+
+  // Auto-set shortcut if not explicitly overridden on this class
+  if (!Object.getOwnPropertyDescriptor(SubClass, 'shortcut')?.value ||
+      (SubClass as any).shortcut === 'unspecified') {
+    ;(SubClass as any).shortcut = `features.${registryId}` as const
+  }
+
+  // Register in the features registry (interceptRegistration sees all statics above)
+  features.register(registryId, SubClass as any)
+
+  // Generate default attach() if not explicitly overridden on this class
+  if (!Object.getOwnPropertyDescriptor(SubClass, 'attach')) {
+    ;(SubClass as any).attach = (container: any) => {
+      features.register(registryId, SubClass as any)
+      return container
+    }
+  }
+
+  return SubClass
+}