@ohos-ports/stacksjs-stx 0.2.287-beta.0

package/dist/production-builder.js

@@ -0,0 +1,146 @@
+import fs from "node:fs";
+import path from "node:path";
+import { CONVENTIONAL_ASSET_OUTPUT, CONVENTIONAL_ASSET_ROOT, resolveConventionalAssetRoot } from "./asset-roots.js";
+import { createRouter } from "./router.js";
+import { buildRuntimeAsset, buildRouterAsset } from "./build-assets.js";
+import { compileTemplate } from "./template-compiler.js";
+import { generateManifest, writeManifest } from "./manifest.js";
+import { injectColorModeBootScript } from "./color-mode-boot.js";
+import { applyHtmlAttrs, ensureDocumentShell } from "./document-shell.js";
+import { extractContainerContent } from "./app-shell.js";
+import { injectCss } from "./dev-server/ts-css.js";
+import { loadStxConfig } from "./config.js";
+const PUBLIC_ASSET_BLOCKLIST = new Set([
+  ".DS_Store",
+  "Thumbs.db",
+  "desktop.ini",
+  ".gitkeep",
+  ".gitignore"
+]);
+function copyPublicAssets(srcDir, destDir) {
+  let copied = 0, bytes = 0;
+  if (!fs.existsSync(srcDir))
+    return { copied, bytes };
+  fs.mkdirSync(destDir, { recursive: !0 });
+  function walk(currentSrc, currentDest) {
+    const entries = fs.readdirSync(currentSrc, { withFileTypes: !0 });
+    for (const entry of entries) {
+      if (PUBLIC_ASSET_BLOCKLIST.has(entry.name))
+        continue;
+      const srcPath = path.join(currentSrc, entry.name), destPath = path.join(currentDest, entry.name);
+      if (entry.isDirectory()) {
+        fs.mkdirSync(destPath, { recursive: !0 });
+        walk(srcPath, destPath);
+      } else if (entry.isFile()) {
+        if (fs.existsSync(destPath))
+          continue;
+        fs.copyFileSync(srcPath, destPath);
+        copied++;
+        bytes += fs.statSync(destPath).size;
+      }
+    }
+  }
+  walk(srcDir, destDir);
+  return { copied, bytes };
+}
+export async function buildForProduction(options = {}) {
+  const startTime = Date.now(), root = path.resolve(options.root || process.cwd()), outputDir = path.resolve(root, options.outputDir || ".output");
+  console.log("[stx build] Starting production build...");
+  let projectConfig = {};
+  try {
+    projectConfig = await loadStxConfig();
+  } catch {}
+  const componentsDir = options.componentsDir ?? projectConfig.componentsDir ?? "components", partialsDir = options.partialsDir ?? projectConfig.partialsDir ?? "partials", layoutsDir = options.layoutsDir ?? projectConfig.layoutsDir ?? "layouts", publicDir = options.publicDir ?? projectConfig.publicDir ?? "public", headConfigDefault = projectConfig.app?.head || {}, colorModeConfig = projectConfig.app?.colorMode, routerContainer = projectConfig.router?.container || "main";
+  if (fs.existsSync(outputDir))
+    fs.rmSync(outputDir, { recursive: !0 });
+  const dirs = [
+    path.join(outputDir, "public", "__stx"),
+    path.join(outputDir, "public", "assets"),
+    path.join(outputDir, "server", "pages"),
+    path.join(outputDir, "server", "fragments")
+  ];
+  for (const dir of dirs)
+    fs.mkdirSync(dir, { recursive: !0 });
+  console.log("[stx build] Discovering routes...");
+  const allRoutes = createRouter(root), excludeDirs = ["components", "layouts", "partials"], routes = allRoutes.filter((r) => {
+    return !excludeDirs.some((dir) => r.pattern.startsWith(`/${dir}/`) || r.pattern === `/${dir}`);
+  });
+  console.log(`[stx build] Found ${routes.length} page routes (${allRoutes.length - routes.length} non-page files excluded)`);
+  console.log("[stx build] Generating shared assets...");
+  const runtimeAsset = buildRuntimeAsset(options.debug), routerAsset = buildRouterAsset();
+  await Bun.write(path.join(outputDir, "public", "__stx", runtimeAsset.filename), runtimeAsset.content);
+  await Bun.write(path.join(outputDir, "public", "__stx", routerAsset.filename), routerAsset.content);
+  console.log(`[stx build] Runtime: ${runtimeAsset.filename} (${(runtimeAsset.content.length / 1024).toFixed(1)}KB)`);
+  console.log(`[stx build] Router: ${routerAsset.filename} (${(routerAsset.content.length / 1024).toFixed(1)}KB)`);
+  console.log("[stx build] Compiling templates...");
+  const compiledPages = [], manifestRoutes = [];
+  for (const route of routes)
+    try {
+      const compiled = await compileTemplate(route.filePath, route.pattern, {
+        componentsDir,
+        partialsDir,
+        layoutsDir,
+        debug: options.debug
+      });
+      compiledPages.push(compiled);
+      compiled.html = compiled.html.replace(/runtime\.__STX_HASH__\.js/g, runtimeAsset.filename).replace(/router\.__STX_HASH__\.js/g, routerAsset.filename);
+      compiled.html = ensureDocumentShell(compiled.html, headConfigDefault, {
+        bodyScripts: [`<script src="/__stx/${routerAsset.filename}"></script>`],
+        ...colorModeConfig && { colorMode: colorModeConfig }
+      });
+      if (colorModeConfig)
+        compiled.html = injectColorModeBootScript(compiled.html, colorModeConfig);
+      if (headConfigDefault.htmlAttrs)
+        compiled.html = applyHtmlAttrs(compiled.html, headConfigDefault.htmlAttrs);
+      if (!/<body[^>]*\bdata-stx=/.test(compiled.html)) {
+        const dataStxMatch = compiled.html.match(/<(?!body\b)[a-zA-Z][a-zA-Z0-9-]*\b[^>]*?\s(data-stx="[^"]+")[^>]*>/);
+        if (dataStxMatch && dataStxMatch[1]) {
+          const dataStxAttr = dataStxMatch[1];
+          compiled.html = compiled.html.replace(" " + dataStxAttr, "");
+          compiled.html = compiled.html.replace(/<body([^>]*)>/, `<body$1 ${dataStxAttr}>`);
+        }
+      }
+      compiled.html = compiled.html.replace(/<style data-css="generated">[\s\S]*?<\/style>\s*/g, "");
+      compiled.html = await injectCss(compiled.html);
+      compiled.fragment = extractContainerContent(compiled.html, routerContainer);
+      const safeRouteName = route.pattern === "/" ? "index" : route.pattern.slice(1).replace(/\//g, "-").replace(/[[\]]/g, "_"), compiledPath = path.join("server", "pages", `${safeRouteName}.compiled.json`), fragmentPath = path.join("server", "fragments", `${safeRouteName}.html`);
+      await Bun.write(path.join(outputDir, compiledPath), JSON.stringify(compiled, null, 2));
+      await Bun.write(path.join(outputDir, fragmentPath), compiled.fragment);
+      manifestRoutes.push({
+        pattern: route.pattern,
+        compiledPath,
+        fragmentPath,
+        isDynamic: compiled.hasServerScripts,
+        hasParams: route.pattern.includes(":") || route.pattern.includes("[")
+      });
+      console.log(`[stx build]   \u2713 ${route.pattern}`);
+    } catch (error) {
+      console.error(`[stx build]   \u2717 ${route.pattern}:`, error instanceof Error ? error.message : error);
+    }
+  const userPublicSrc = path.resolve(root, publicDir);
+  if (fs.existsSync(userPublicSrc)) {
+    const { copied, bytes } = copyPublicAssets(userPublicSrc, path.join(outputDir, "public"));
+    if (copied > 0)
+      console.log(`[stx build] Copied ${copied} public asset${copied === 1 ? "" : "s"} (${(bytes / 1024).toFixed(1)}KB) from ${publicDir}/`);
+  }
+  const conventionalAssetSrc = resolveConventionalAssetRoot(root);
+  if (conventionalAssetSrc) {
+    const { copied, bytes } = copyPublicAssets(conventionalAssetSrc, path.join(outputDir, "public", CONVENTIONAL_ASSET_OUTPUT));
+    if (copied > 0)
+      console.log(`[stx build] Copied ${copied} asset${copied === 1 ? "" : "s"} (${(bytes / 1024).toFixed(1)}KB) from ${CONVENTIONAL_ASSET_ROOT}/`);
+  }
+  const assets = {
+    runtime: runtimeAsset.filename,
+    router: routerAsset.filename
+  }, manifest = generateManifest(manifestRoutes, assets, outputDir);
+  writeManifest(manifest, outputDir);
+  const duration = Date.now() - startTime;
+  console.log(`
+[stx build] Done in ${duration}ms \u2014 ${compiledPages.length} pages compiled`);
+  return {
+    pageCount: compiledPages.length,
+    assets,
+    outputDir,
+    duration
+  };
+}

package/dist/production-server.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Start the production server.
+ *
+ * Serves pre-built pages from .output/ with minimal per-request work:
+ * - Static assets: served from disk with immutable cache headers
+ * - SPA fragments: served from pre-extracted HTML files
+ * - Static pages: served directly (zero processing)
+ * - Dynamic pages: hydrated with request-time data
+ */
+export declare function startProductionServer(options?: ProductionServerOptions): Promise<{ port: number, stop: () => void }>;
+/**
+ * Production server configuration.
+ */
+export declare interface ProductionServerOptions {
+  outputDir?: string
+  port?: number
+  onRequest?: (req: Request) => Response | Promise<Response> | null | Promise<null>
+  apiRoutes?: Record<string, (req: Request) => Response | Promise<Response>>
+}

package/dist/production-server.js

@@ -0,0 +1,208 @@
+import fs from "node:fs";
+import path from "node:path";
+import { serve, default as Bun } from "./bun-shim.js";
+import { loadManifest } from "./manifest.js";
+import { hydrateTemplateStream, hydrateFragment } from "./template-hydrator.js";
+import { extractLayoutMetadata } from "./app-shell.js";
+import { pageShipsSignalsRuntime } from "./runtime-injection.js";
+import { patternToRegex } from "stx-router";
+import { compressResponse } from "./compression.js";
+import { actionRedirectResponse, isActionableMethod } from "./page-action.js";
+import { FRAGMENT_CACHE_CONTROL, isSpaNavRequest, spaNavVaryHeaders } from "./spa-nav.js";
+const MIME_TYPES = {
+  ".js": "application/javascript",
+  ".mjs": "application/javascript",
+  ".css": "text/css",
+  ".json": "application/json",
+  ".html": "text/html",
+  ".txt": "text/plain",
+  ".xml": "application/xml",
+  ".pdf": "application/pdf",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".avif": "image/avif",
+  ".svg": "image/svg+xml",
+  ".ico": "image/x-icon",
+  ".bmp": "image/bmp",
+  ".mp4": "video/mp4",
+  ".webm": "video/webm",
+  ".ogg": "audio/ogg",
+  ".mp3": "audio/mpeg",
+  ".wav": "audio/wav",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".otf": "font/otf",
+  ".eot": "application/vnd.ms-fontobject"
+};
+export async function startProductionServer(options = {}) {
+  const outputDir = path.resolve(options.outputDir || ".output"), port = options.port || 3000, manifest = loadManifest(outputDir);
+  if (!manifest) {
+    console.error("[stx] No build manifest found. Run `stx build` first.");
+    process.exit(1);
+  }
+  console.log(`[stx] Production server loading ${manifest.routes.length} routes...`);
+  const compiledTemplates = new Map, fragmentCache = new Map, layoutMetadataCache = new Map, runtimeCache = new Map;
+  for (const route of manifest.routes)
+    try {
+      const compiledPath = path.join(outputDir, route.compiledPath), compiled = JSON.parse(await Bun.file(compiledPath).text());
+      compiledTemplates.set(route.pattern, compiled);
+      layoutMetadataCache.set(route.pattern, extractLayoutMetadata(compiled.html));
+      runtimeCache.set(route.pattern, pageShipsSignalsRuntime(compiled.html));
+      const fragmentPath = path.join(outputDir, route.fragmentPath);
+      if (await Bun.file(fragmentPath).exists())
+        fragmentCache.set(route.pattern, await Bun.file(fragmentPath).text());
+    } catch (error) {
+      console.warn(`[stx] Failed to load route ${route.pattern}:`, error);
+    }
+  const exactRoutes = new Map, paramRoutes = [];
+  for (const route of manifest.routes)
+    if (route.hasParams) {
+      const { regex, params: paramNames } = patternToRegex(route.pattern);
+      paramRoutes.push({ regex, route, paramNames });
+    } else
+      exactRoutes.set(route.pattern, route);
+  const server = serve({
+    port,
+    async fetch(request) {
+      return compressResponse(request, await (async () => {
+        const pathname = new URL(request.url).pathname;
+        if (options.onRequest) {
+          const response = await options.onRequest(request);
+          if (response)
+            return response;
+        }
+        if (options.apiRoutes?.[pathname])
+          return options.apiRoutes[pathname](request);
+        if ((request.method === "GET" || request.method === "HEAD") && pathname !== "/") {
+          const publicRoot = path.resolve(outputDir, "public");
+          let safePathname;
+          try {
+            safePathname = decodeURIComponent(pathname);
+          } catch {
+            safePathname = pathname;
+          }
+          if (!safePathname.includes("\x00")) {
+            const resolvedPath = path.resolve(publicRoot, `.${safePathname}`);
+            if (resolvedPath === publicRoot || resolvedPath.startsWith(`${publicRoot}${path.sep}`))
+              try {
+                if (fs.existsSync(resolvedPath) && fs.statSync(resolvedPath).isFile()) {
+                  const ext = path.extname(resolvedPath).toLowerCase(), contentType = MIME_TYPES[ext] || "application/octet-stream", isFingerprinted = pathname.startsWith("/__stx/") || /\.[0-9a-f]{8}\./.test(pathname);
+                  return new Response(Bun.file(resolvedPath), {
+                    headers: {
+                      "Content-Type": contentType,
+                      "Cache-Control": isFingerprinted ? "public, max-age=31536000, immutable" : "public, max-age=3600"
+                    }
+                  });
+                }
+              } catch {}
+          }
+        }
+        const isSpaNav = isSpaNavRequest(request);
+        let matchedRoute = null, params = {};
+        matchedRoute = exactRoutes.get(pathname) || null;
+        if (!matchedRoute)
+          for (const { regex, route, paramNames } of paramRoutes) {
+            const match = pathname.match(regex);
+            if (match) {
+              matchedRoute = route;
+              paramNames.forEach((name, i) => {
+                params[name] = match[i + 1];
+              });
+              break;
+            }
+          }
+        if (!matchedRoute) {
+          const errorPage = exactRoutes.get("/404") || null;
+          if (errorPage) {
+            const compiled = compiledTemplates.get(errorPage.pattern);
+            if (compiled)
+              return new Response(compiled.html, {
+                status: 404,
+                headers: { "Content-Type": "text/html" }
+              });
+          }
+          return new Response("Not Found", { status: 404 });
+        }
+        if (isSpaNav) {
+          const fragment = fragmentCache.get(matchedRoute.pattern);
+          if (fragment) {
+            const layoutMetadata = layoutMetadataCache.get(matchedRoute.pattern);
+            return new Response(fragment, {
+              headers: {
+                "Content-Type": "text/html",
+                "X-STX-Fragment": "true",
+                ...runtimeCache.has(matchedRoute.pattern) ? { "X-STX-Runtime": runtimeCache.get(matchedRoute.pattern) ? "true" : "false" } : {},
+                ...layoutMetadata ? {
+                  "X-STX-Layout": layoutMetadata.layout,
+                  "X-STX-Layout-Group": layoutMetadata.group
+                } : {},
+                ...spaNavVaryHeaders(),
+                "Cache-Control": FRAGMENT_CACHE_CONTROL
+              }
+            });
+          }
+        }
+        const isMutating = isActionableMethod(request.method), compiled = compiledTemplates.get(matchedRoute.pattern);
+        if (!compiled) {
+          const errorPage = exactRoutes.get("/500") || null;
+          if (errorPage) {
+            const compiledError = compiledTemplates.get(errorPage.pattern);
+            if (compiledError)
+              return new Response(compiledError.html, {
+                status: 500,
+                headers: { "Content-Type": "text/html" }
+              });
+          }
+          return new Response("Internal Server Error", { status: 500 });
+        }
+        if (!isMutating && !compiled.hasServerScripts && Object.keys(compiled.placeholders).length === 0)
+          return new Response(compiled.html, {
+            status: compiled.status ?? 200,
+            headers: {
+              "Content-Type": "text/html",
+              ...spaNavVaryHeaders(),
+              "Cache-Control": "public, max-age=60"
+            }
+          });
+        try {
+          const { html, boundaries, redirect, cookies, status, headers: pageHeaders } = await hydrateTemplateStream(compiled, {
+            params,
+            request,
+            method: request.method
+          });
+          if (redirect)
+            return actionRedirectResponse(redirect, cookies, pageHeaders);
+          if (boundaries && boundaries.length > 0) {
+            const { renderStreamingPage, streamToResponse } = await import("./streaming.js");
+            return streamToResponse(renderStreamingPage(html, boundaries, { timeoutMs: 30000 }), {
+              status: status ?? compiled.status ?? 200,
+              headers: { "Cache-Control": "no-cache", ...pageHeaders }
+            });
+          }
+          const headers = new Headers({
+            "Content-Type": "text/html",
+            ...spaNavVaryHeaders(),
+            "Cache-Control": "no-cache"
+          });
+          for (const cookie of cookies ?? [])
+            headers.append("Set-Cookie", cookie);
+          for (const [name, value] of Object.entries(pageHeaders ?? {}))
+            headers.set(name, value);
+          return new Response(html, { status: status ?? compiled.status ?? 200, headers });
+        } catch (error) {
+          console.error(`[stx] Hydration error for ${pathname}:`, error);
+          return new Response(compiled.html, {
+            headers: { "Content-Type": "text/html" }
+          });
+        }
+      })());
+    }
+  });
+  console.log(`[stx] Production server running at http://localhost:${port}`);
+  console.log(`[stx] Serving ${manifest.routes.length} routes (${compiledTemplates.size} pre-loaded)`);
+  return { port, stop: () => server.stop() };
+}

package/dist/prop-sentinels.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Sentinel values used while resolving component props.
+ *
+ * A leaf module on purpose: `component-renderer.ts` imports `./builtins`, so a
+ * builtin importing the renderer back would be a cycle. Both sides import this
+ * instead.
+ *
+ * @module prop-sentinels
+ */
+/**
+ * Marks a prop that was written as a bare HTML boolean attribute — `<X open>`
+ * rather than `<X open="true">`.
+ *
+ * It carries a leading NUL precisely so it cannot collide with an author-written
+ * value, which also means it must never survive into a response: a NUL byte
+ * makes the document invalid UTF-8, and tools treat the file as binary. `grep`
+ * in particular goes SILENT on it — not zero matches, no output at all — so a
+ * verification step that greps rendered HTML returns an empty string and reads
+ * as a pass (stacksjs/stx#1816).
+ */
+export declare const BOOLEAN_ATTRIBUTE_SENTINEL = "\0stx-boolean-attribute";
+/** Is this value the bare-boolean-attribute marker? */
+export declare function isBooleanAttributeSentinel(value: unknown): boolean;
+/**
+ * Last-resort guard for anything about to be written into a response.
+ *
+ * Nothing should reach output carrying a NUL, but the cost of one escaping is
+ * an invalid document and a silent grep, which is far worse than the cost of
+ * this check.
+ */
+export declare function stripControlChars(value: string): string;

package/dist/prop-sentinels.js

@@ -0,0 +1,7 @@
+export const BOOLEAN_ATTRIBUTE_SENTINEL = "\x00stx-boolean-attribute";
+export function isBooleanAttributeSentinel(value) {
+  return value === BOOLEAN_ATTRIBUTE_SENTINEL;
+}
+export function stripControlChars(value) {
+  return value.indexOf("\x00") === -1 ? value : value.replace(/\0/g, "");
+}

package/dist/props.d.ts

@@ -0,0 +1,216 @@
+/**
+ * Define component props with type safety and validation.
+ *
+ * Takes an inline object type or a named `interface`/`type` — the named form is
+ * shown first because it is the one the framework scaffolds, and because every
+ * example here used to be inline. An inline literal has an implicit index
+ * signature and a named `interface` does not, so an inline-only docstring
+ * demonstrated the one spelling that could not fail (stacksjs/stx#1917).
+ *
+ * @example
+ * ```typescript
+ * // A named type, inline or imported — interface and type alias both work
+ * interface CardProps {
+ *   title: string
+ *   count: number
+ * }
+ * const props = defineProps<CardProps>()
+ *
+ * // Or inline
+ * const props = defineProps<{
+ *   title: string
+ *   count: number
+ * }>()
+ *
+ * // With validation and defaults
+ * const props = defineProps<{
+ *   title: string
+ *   count?: number
+ *   status: 'active' | 'inactive'
+ * }>({
+ *   title: { required: true },
+ *   count: { default: 0 },
+ *   status: {
+ *     default: 'active',
+ *     validator: (v) => ['active', 'inactive'].includes(v)
+ *   }
+ * })
+ * ```
+ */
+export declare function defineProps<T extends PropsShape>(definitions?: PropsDefinition<T>): T;
+/**
+ * Define props with runtime validation.
+ * Use this when you need validation errors at runtime.
+ */
+export declare function definePropsWithValidation<T extends PropsShape>(definitions: PropsDefinition<T>, options?: {
+    componentName?: string
+    throwOnError?: boolean
+    logWarnings?: boolean
+  }): { props: T; validation: PropValidationResult };
+/**
+ * Define default values for props.
+ *
+ * @example
+ * ```typescript
+ * const props = withDefaults(defineProps<{
+ *   title: string
+ *   count?: number
+ *   items?: string[]
+ * }>(), {
+ *   count: 0,
+ *   items: () => []
+ * })
+ * ```
+ */
+export declare function withDefaults<T extends PropsShape>(props: T, defaults: Partial<{ [K in keyof T]: T[K] | (() => T[K]) }>): T;
+/**
+ * Create a prop type definition for a specific type.
+ */
+export declare function prop<T>(options: PropOptions<T>): PropOptions<T>;
+/**
+ * Create a required prop.
+ */
+export declare function required<T>(type?: PropType<T>): PropOptions<T>;
+/**
+ * Create an optional prop with default.
+ */
+export declare function optional<T>(defaultValue: T | (() => T), type?: PropType<T>): PropOptions<T>;
+/**
+ * Create a prop with a validator.
+ */
+export declare function validated<T>(validator: (value: T) => boolean, options?: Omit<PropOptions<T>, 'validator'>): PropOptions<T>;
+/**
+ * Create a prop that accepts one of specific values.
+ */
+export declare function oneOf<T extends string | number>(values: readonly T[], options?: Omit<PropOptions<T>, 'validator'>): PropOptions<T>;
+/**
+ * Create a prop for array of specific type.
+ */
+export declare function arrayOf<T>(_itemType: PropType<T>, options?: Omit<PropOptions<T[]>, 'type'>): PropOptions<T[]>;
+/**
+ * Create a prop for object with specific shape.
+ */
+export declare function shape<T extends PropsShape>(_shape: PropsDefinition<T>, options?: Omit<PropOptions<T>, 'type'>): PropOptions<T>;
+/**
+ * Process props passed to a component.
+ * Called internally during component rendering.
+ */
+export declare function processComponentProps(rawProps: Record<string, unknown>, definitions?: PropsDefinition<Record<string, unknown>>, componentName?: string): Record<string, unknown>;
+/**
+ * Define component events (emits).
+ *
+ * @example
+ * ```typescript
+ * const emit = defineEmits<{
+ *   'update:value': string
+ *   'submit': { data: FormData }
+ *   'close': void
+ * }>()
+ *
+ * // Usage
+ * emit('update:value', 'new value')
+ * emit('submit', { data: formData })
+ * emit('close', undefined)
+ * ```
+ */
+export declare function defineEmits<E extends PropsShape>(): EmitFn<E>;
+/**
+ * Expose component methods/properties to parent.
+ *
+ * @example
+ * ```typescript
+ * defineExpose({
+ *   focus: () => inputRef.value?.focus(),
+ *   reset: () => { value = '' },
+ *   value: computed(() => internalValue)
+ * })
+ * ```
+ */
+export declare function defineExpose<T extends PropsShape>(exposed: T): void;
+/**
+ * Generate TypeScript interface from prop definitions.
+ * Useful for documentation and type generation.
+ */
+export declare function generatePropsInterface(componentName: string, definitions: PropsDefinition<Record<string, unknown>>): string;
+/** Prop definition options */
+export declare interface PropOptions<T = unknown> {
+  type?: PropType<T> | PropType<T>[]
+  required?: boolean
+  default?: T | (() => T)
+  validator?: (value: T) => boolean
+  description?: string
+}
+/** Prop validation error */
+export declare interface PropValidationError {
+  prop: string
+  message: string
+  value: unknown
+  expected?: string
+}
+/** Prop validation result */
+export declare interface PropValidationResult {
+  valid: boolean
+  errors: PropValidationError[]
+  warnings: string[]
+}
+/** Supported prop types */
+export type PropType<T> = | StringConstructor
+  | NumberConstructor
+  | BooleanConstructor
+  | ArrayConstructor
+  | ObjectConstructor
+  | FunctionConstructor
+  | DateConstructor
+  | SymbolConstructor
+  | { new (...args: unknown[]): T }
+  | PropType<T>[];
+/**
+ * The constraint every props, emits and expose generic is bounded by.
+ *
+ * `object` rather than `Record<string, unknown>`, and the difference is not
+ * cosmetic: **a TypeScript `interface` does not satisfy an index signature.**
+ * Only a type alias gets an implicit one, so
+ *
+ *     interface CardProps { title: string }
+ *     defineProps<CardProps>()   // TS2344, TS2345
+ *     type CardProps = { title: string }
+ *     defineProps<CardProps>()   // fine
+ *
+ * differ on the keyword alone. `interface` is the form the framework scaffolds
+ * — `storage/framework/defaults/` declares props with it 44 times and with a
+ * type alias zero times — so the constraint rejected the entire scaffolded
+ * corpus (stacksjs/stx#1917).
+ *
+ * Two things hid it. Every example in the docstrings passes an inline object
+ * literal, which HAS an implicit index signature and so always passed; the
+ * error appears only once the type is named, which is the moment it is reused
+ * or exported. And apps import from `stx`, which is not a package anyone can
+ * install — the module resolved to `any`, the constraint was never enforced,
+ * and the component type-checked. Correcting the specifier in one app turned 18
+ * "Cannot find module" errors into 36 constraint errors.
+ *
+ * Named rather than written out seven times so the reason lives in one place
+ * and the sites cannot drift apart. `object` still rejects `string`, `number`
+ * and `undefined`, which is everything this constraint has to do.
+ */
+export type PropsShape = object;
+/** Props definition object */
+export type PropsDefinition<T> = {
+  [K in keyof T]?: PropOptions<T[K]> | PropType<T[K]>
+}
+/** Extracted prop types */
+export type ExtractPropTypes<T extends PropsDefinition<unknown>> = {
+  [K in keyof T]: T[K] extends PropOptions<infer V>
+    ? V
+    : T[K] extends PropType<infer V>
+      ? V
+      : unknown
+}
+/** Event handler type */
+// eslint-disable-next-line pickier/no-unused-vars
+export type EventHandler<T = unknown> = (payload: T) => void;
+/** Emit function type */
+export type EmitFn<E extends PropsShape> = <K extends keyof E>(
+  event: K,
+  payload: E[K],
+) => void;