@stdout-design/core 0.1.1

package/dist/index.d.mts

@@ -0,0 +1,460 @@
+import { a as isZodObject, n as PropValidationError, o as validateProps, r as PropValidationIssue, s as zodToJsonSchemaShape, t as PropSchema } from "./validation-BUNZnc-5.mjs";
+import { z } from "zod";
+import { fromJsx } from "takumi-js/helpers/jsx";
+import { ComponentType } from "react";
+import { Node } from "takumi-js";
+//#region src/shared/types.d.ts
+interface TemplateEntry {
+  componentPath: string;
+  description?: string;
+}
+interface Preset {
+  id: string;
+  width: number;
+  height: number;
+  platform: string;
+}
+interface StudioConfig {
+  templates: Record<string, TemplateEntry>;
+  presets: Preset[];
+  defaultPreset?: string;
+  locales?: string[];
+  outDir?: string;
+}
+interface TemplateModule {
+  default: (props: Record<string, unknown>) => unknown;
+  propsSchema: z.ZodObject<Record<string, z.ZodTypeAny>>;
+}
+//#endregion
+//#region src/shared/config-schema.d.ts
+declare const studioConfigSchema: z.ZodObject<{
+  defaultPreset: z.ZodOptional<z.ZodString>;
+  locales: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  outDir: z.ZodOptional<z.ZodString>;
+  presets: z.ZodArray<z.ZodObject<{
+    height: z.ZodNumber;
+    id: z.ZodString;
+    platform: z.ZodString;
+    width: z.ZodNumber;
+  }, z.core.$strip>>;
+  templates: z.ZodRecord<z.ZodString, z.ZodObject<{
+    componentPath: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+}, z.core.$strip>;
+//#endregion
+//#region src/shared/render.d.ts
+interface CompiledTemplate {
+  node: Node;
+  stylesheets: string[];
+}
+declare const compileTemplate: (element: Parameters<typeof fromJsx>[0], options?: Parameters<typeof fromJsx>[1]) => Promise<CompiledTemplate>;
+//#endregion
+//#region src/shared/error-codes.d.ts
+declare const ErrorCode: {
+  readonly API_ERROR: "API_ERROR";
+  readonly CACHE_CLEANUP_FAILED: "CACHE_CLEANUP_FAILED";
+  readonly CACHE_CORRUPT_ENTRY: "CACHE_CORRUPT_ENTRY";
+  readonly CACHE_INIT_FAILED: "CACHE_INIT_FAILED";
+  readonly CACHE_WRITE_FAILED: "CACHE_WRITE_FAILED";
+  readonly CONFIG_INVALID: "CONFIG_INVALID";
+  readonly CONFIG_NOT_FOUND: "CONFIG_NOT_FOUND";
+  readonly FONT_REGISTRATION_FAILED: "FONT_REGISTRATION_FAILED";
+  readonly INTERNAL_ERROR: "INTERNAL_ERROR";
+  readonly LOCALE_LOAD_FAILED: "LOCALE_LOAD_FAILED";
+  readonly PROP_VALIDATION_FAILED: "PROP_VALIDATION_FAILED";
+  readonly RENDERER_NOT_INITIALIZED: "RENDERER_NOT_INITIALIZED";
+  readonly RENDER_FAILED: "RENDER_FAILED";
+  readonly SSE_ERROR: "SSE_ERROR";
+  readonly TEMPLATE_INVALID_EXPORT: "TEMPLATE_INVALID_EXPORT";
+  readonly TEMPLATE_LOAD_FAILED: "TEMPLATE_LOAD_FAILED";
+  readonly TEMPLATE_NOT_FOUND: "TEMPLATE_NOT_FOUND";
+  readonly UI_RENDER_ERROR: "UI_RENDER_ERROR";
+};
+type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+declare class AppError extends Error {
+  readonly code: ErrorCode;
+  readonly context: Record<string, unknown>;
+  constructor(code: ErrorCode, message: string, context?: Record<string, unknown>);
+}
+//#endregion
+//#region src/shared/logger.d.ts
+type LogLevel = "debug" | "info" | "warn" | "error";
+declare const logDebug: (message: string, context?: Record<string, unknown>) => void;
+declare const logInfo: (message: string, context?: Record<string, unknown>) => void;
+declare const logWarn: (message: string, context?: Record<string, unknown>) => void;
+declare const logError: (code: ErrorCode, message: string, context?: Record<string, unknown>) => void;
+//#endregion
+//#region src/node/cache-keys.d.ts
+/**
+ * Cache key derivation, shared by every component that needs to name a
+ * cache entry consistently. Pulled out of the old monolithic RenderCache
+ * specifically so CompileCache, MetadataStore, and FsStore all derive keys
+ * the same way -- a duplicated hashing implementation across components
+ * is exactly the kind of drift risk this split is meant to eliminate.
+ */
+interface CompileCacheKeyInput {
+  templateId: string;
+  templateContentHash: string;
+  propsJSON: string;
+}
+interface PixelCacheKeyInput {
+  templateContentHash: string;
+  propsJSON: string;
+  width: number;
+  height: number;
+  format?: string;
+}
+declare const createCompileCacheKey: (input: CompileCacheKeyInput) => string;
+declare const createPixelCacheKey: (input: PixelCacheKeyInput) => string;
+//#endregion
+//#region src/node/render-cache.d.ts
+interface CacheStats {
+  compiled: {
+    entries: number;
+  };
+  pixels: {
+    entries: number;
+    sizeBytes: number;
+    maxSizeBytes: number;
+  };
+  cacheDir: string;
+}
+interface RenderCacheOptions {
+  cacheDir?: string;
+  maxSizeMB?: number;
+  /** Max in-memory compiled entries to retain. Default 100. */
+  compiledMaxEntries?: number;
+  /** Caps concurrent Pixel cache disk writes/reads. Default: unbounded (matches pre-split behavior). */
+  maxConcurrentWrites?: number;
+  /** Debounce window between a write and the next eviction check. Default 250ms. */
+  evictionDebounceMs?: number;
+}
+interface SweepOutcome {
+  freedBytes: number;
+}
+/**
+ * Content-addressed two-stage render cache -- coordinator.
+ *
+ * This class used to own SQLite calls, filesystem calls, atomicity
+ * handling, and eviction policy directly (~400 lines, five
+ * responsibilities). It now owns none of that: it constructs and wires
+ * together CompileCache, MetadataStore, FsStore, and EvictionCoordinator,
+ * and exposes the exact same public method signatures CLI, MCP, and
+ * dev-server already depend on. No downstream consumer needs to change
+ * anything as a result of this refactor.
+ */
+declare class RenderCache {
+  private readonly cacheDir;
+  private readonly maxSizeBytes;
+  private readonly compiled;
+  private readonly maxConcurrentWrites;
+  private readonly evictionDebounceMs;
+  private metadata;
+  private fsStore;
+  private eviction;
+  private initialized;
+  static readonly createCompileCacheKey: typeof createCompileCacheKey;
+  static readonly createPixelCacheKey: typeof createPixelCacheKey;
+  constructor(options?: RenderCacheOptions);
+  init(): Promise<void>;
+  close(): void;
+  getCompiled(key: string): unknown;
+  setCompiled(key: string, value: unknown): void;
+  setCompiledWithContentHash(key: string, contentHash: string, value: unknown): void;
+  invalidateCompiledByContentHash(contentHash: string): void;
+  clearCompiled(): void;
+  getPixels(key: string): Promise<Buffer | null>;
+  setPixels(key: string, bytes: Buffer, width: number, height: number, format?: string): Promise<string>;
+  stats(): Promise<CacheStats>;
+  /** Full wipe -- unlike a budget-triggered sweep, always removes everything, still lock-coordinated. */
+  clean(): Promise<SweepOutcome>;
+  private performSweep;
+  private requireMetadata;
+  private recoverMetadata;
+  private requireFsStore;
+  private requireEviction;
+}
+//#endregion
+//#region src/node/takumi-types-shim.d.ts
+/**
+ * Type-only shim for `@takumi-rs/core` (as re-exported by `takumi-js/node`).
+ *
+ * Migrated for Takumi v2. The v1 shim existed to work around a broken
+ * `export.d.ts` re-export chain in @takumi-rs/core@1.8.6 that hid
+ * `render`/`measure` and several option types from consumers on
+ * `moduleResolution: "nodenext"`. This file re-declares the v2 surface we
+ * actually use, backed by the real runtime export.
+ *
+ * TODO(verify-on-upgrade): the v1 packaging bug this shim worked around
+ * has not been independently re-verified against the v2 release actually
+ * installed. Once upgraded, run the same isolated-probe check described
+ * in the v1 version of this file (import the types directly from
+ * "takumi-js/node" in a throwaway file and see if `render`/`measure`/
+ * `registerFont` resolve). If they do, delete this file and switch all
+ * importers back to `takumi-js/node` directly. Tracked against the
+ * upstream repo: https://github.com/kane50613/takumi
+ *
+ * v2 breaking changes reflected below (see /docs/upgrade/v2):
+ * - `new Renderer(options)` -> `new Renderer()`. The constructor takes no
+ *   arguments; fonts and images are now per-render options instead of
+ *   construction-time state.
+ * - `loadFont` / `loadFonts` / `loadFontSync` -> `registerFont`. Use this
+ *   only to preload a font once and reuse it across many renders; most
+ *   callers should just pass `fonts` on the render/measure call instead.
+ * - The persistent image store and `GlobalContext` are gone.
+ *   `putPersistentImage` / `clearImageStore` no longer exist. Every image
+ *   a render needs must be passed through `images`, keyed by `src`.
+ * - `fetchedResources` -> `images`. `images` also accepts a group form
+ *   (`{ sources, fetch, fetchCache }`) that combines pre-fetched entries,
+ *   a custom fetch implementation, and a shared byte cache.
+ * - `format` stays a string, but `quality` (jpeg / lossy webp) and
+ *   `lossless` (webp) are now separate optional fields instead of one
+ *   combined quality argument.
+ * - `fonts` entries may be bare URL strings, fetched and cached on demand,
+ *   in addition to loaded font descriptors / raw bytes.
+ */
+interface FontDescriptor {
+  name?: string;
+  data: Uint8Array | ArrayBuffer | Buffer | (() => Promise<ArrayBuffer | Uint8Array>);
+  weight?: number;
+  style?: "normal" | "italic" | "oblique" | `oblique ${number}deg` | (string & {});
+}
+/** A font supplied to a render/measure call: a loaded descriptor, raw bytes, or a bare URL fetched on demand. */
+type Font = FontDescriptor | Uint8Array | ArrayBuffer | Buffer | string;
+interface ImageSourceEntry {
+  src: string;
+  data: Uint8Array | ArrayBuffer;
+}
+/** Shared byte cache across renders -- dedupes concurrent fetches of the same URL. */
+type ImageFetchCache = Map<string, Promise<ArrayBuffer>>;
+type ImageFetchFn = (url: string, signal?: AbortSignal) => Promise<ArrayBuffer>;
+interface ImageResourcesGroup {
+  /** Pre-fetched entries, keyed by src. Not re-fetched. */
+  sources?: ImageSourceEntry[];
+  fetch?: ImageFetchFn;
+  timeout?: number;
+  fetchCache?: ImageFetchCache;
+}
+/** Either a flat list of pre-fetched images, or the group form with fetch behavior + a shared cache. */
+type ImagesOption = ImageSourceEntry[] | ImageResourcesGroup;
+type OutputFormat$1 = "webp" | "png" | "jpeg" | "ico" | "raw";
+type DitheringAlgorithm = "none" | "ordered-bayer" | "floyd-steinberg";
+interface RenderOptions {
+  width?: number;
+  height?: number;
+  format?: OutputFormat$1;
+  /** JPEG and lossy WebP only. */
+  quality?: number;
+  /** WebP only (napi binding). Ignored on wasm, where WebP is always lossless. */
+  lossless?: boolean;
+  drawDebugBorder?: boolean;
+  images?: ImagesOption;
+  /** Fonts needed for this render. Descriptors, raw bytes, or bare URLs. */
+  fonts?: Font[];
+  /** Ordered fallback chain of family names. Defaults to every registered family in registration order. */
+  fontFamilies?: string[];
+  /** BCP-47 language tag for locale-aware shaping. Inherited by children. */
+  lang?: string;
+  stylesheets?: string[];
+  devicePixelRatio?: number;
+  timeMs?: number;
+  dithering?: DitheringAlgorithm;
+}
+interface MeasuredTextRun {
+  text: string;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+interface MeasuredNode {
+  width: number;
+  height: number;
+  transform: [number, number, number, number, number, number];
+  children: MeasuredNode[];
+  runs: MeasuredTextRun[];
+}
+//#endregion
+//#region src/node/renderer.d.ts
+/**
+ * Preload a font once and reuse it across many renders without re-passing
+ * its bytes on every call. Optional -- per Takumi's v2 guidance, passing
+ * `fonts` directly in a render/measure call's options covers most cases.
+ */
+declare const registerFont: (font: Font, signal?: AbortSignal) => Promise<string[]>;
+interface RenderOutput {
+  bytes: Buffer;
+  width: number;
+  height: number;
+  format: NonNullable<RenderOptions["format"]>;
+}
+/**
+ * Renders a compiled template to pixels.
+ *
+ * `width`/`height` are REQUIRED here, not optional pass-through fields.
+ * Takumi's `render()` returns only a Buffer -- it does not report back the
+ * dimensions it used, so auto-sized output isn't supported by this
+ * wrapper. Callers that need auto-sizing must call `measureTemplate` first
+ * and pass the resulting width/height through explicitly (see
+ * `renderAutoSized` below).
+ *
+ * Any `fonts`/`fontFamilies`/`images` the template needs must be supplied
+ * via `options` -- there is no construction-time renderer config to fall
+ * back on in v2.
+ */
+declare const renderToPixels: (template: CompiledTemplate, dimensions: {
+  width: number;
+  height: number;
+}, options?: Omit<RenderOptions, "width" | "height">, signal?: AbortSignal) => Promise<RenderOutput>;
+declare const measureTemplate: (template: CompiledTemplate, options?: RenderOptions, signal?: AbortSignal) => Promise<MeasuredNode>;
+/**
+ * Convenience: measure to discover natural dimensions, then render at
+ * those dimensions in one call. This is the "auto-size" path -- it costs
+ * one extra round-trip into the renderer vs. passing explicit dimensions,
+ * so prefer explicit width/height (e.g. from a chosen output preset) when
+ * you have them.
+ */
+declare const renderAutoSized: (template: CompiledTemplate, options?: RenderOptions, signal?: AbortSignal) => Promise<RenderOutput>;
+//#endregion
+//#region src/batch/types.d.ts
+type OutputFormat = "webp" | "png" | "jpeg" | "ico" | "raw";
+interface MatrixCell {
+  rowIndex: number;
+  rowKey: string;
+  locale: string;
+  preset: Pick<Preset, "id" | "width" | "height">;
+  props: Record<string, unknown>;
+}
+interface RenderOneInput {
+  compiledTemplate: CompiledTemplate;
+  templateId: string;
+  contentHash: string;
+  props: Record<string, unknown>;
+  width: number;
+  height: number;
+  locale?: string;
+  format?: OutputFormat;
+  cache: RenderCache;
+  outDir: string;
+  filename: string;
+  signal?: AbortSignal;
+  renderOptions?: Pick<RenderOptions, "fonts" | "fontFamilies" | "lang"> & Record<string, unknown>;
+}
+interface RenderOneOutput {
+  outputPath: string;
+  cacheHit: boolean;
+  durationMs: number;
+}
+interface ManifestEntry {
+  rowIndex: number;
+  locale: string;
+  preset: string;
+  outputPath: string;
+  cacheHit: boolean;
+}
+interface Manifest {
+  status: "completed" | "aborted";
+  completedCount: number;
+  totalCount: number;
+  succeeded: ManifestEntry[];
+  failed: {
+    rowIndex: number;
+    locale: string;
+    preset: string;
+    error: string;
+  }[];
+}
+//#endregion
+//#region src/batch/matrix.d.ts
+interface MatrixLocaleInput {
+  id: string;
+  data?: Record<string, unknown>;
+}
+interface DataRow {
+  key?: string;
+  id?: string;
+  slug?: string;
+  [key: string]: unknown;
+}
+interface MatrixInput {
+  rows: DataRow[];
+  locales: MatrixLocaleInput[];
+  presets: Pick<Preset, "id" | "width" | "height">[];
+  baseProps?: Record<string, unknown>;
+}
+/**
+ * Expands rows × locales × presets into a flat array of matrix cells.
+ * Locale data is merged into props during expansion so each cell carries
+ * fully resolved props.
+ */
+declare const expandMatrix: (input: MatrixInput) => MatrixCell[];
+//#endregion
+//#region src/batch/render-one.d.ts
+declare const renderOne: (input: RenderOneInput) => Promise<RenderOneOutput>;
+//#endregion
+//#region src/batch/naming.d.ts
+interface NamingOptions {
+  templateId: string;
+  locale: string;
+  presetId: string;
+  rowKey: string;
+  format?: string;
+}
+declare const generateOutputFilename: (options: NamingOptions) => string;
+//#endregion
+//#region src/batch/manifest.d.ts
+declare const writeManifest: (filePath: string, manifest: Manifest) => Promise<void>;
+//#endregion
+//#region src/batch/single.d.ts
+interface SingleInput {
+  component: ComponentType<any>;
+  propsSchema: PropSchema;
+  props: Record<string, unknown>;
+  preset: {
+    id: string;
+    width: number;
+    height: number;
+  };
+  outDir?: string;
+  format?: "webp" | "png" | "jpeg" | "ico" | "raw";
+}
+interface SingleOutput {
+  outputPath: string;
+}
+declare const renderComponent: (input: SingleInput) => Promise<SingleOutput>;
+//#endregion
+//#region src/batch/batch.d.ts
+interface BatchInput {
+  rootDir: string;
+  templateId: string;
+  dataFile?: string;
+  rows?: Record<string, unknown>[];
+  baseProps?: Record<string, unknown>;
+  presets?: string[];
+  locales?: string[];
+  outDir?: string;
+  cacheDir?: string;
+  concurrency?: number;
+  failFast?: boolean;
+}
+interface BatchOutput {
+  manifest: Manifest;
+  elapsedMs: number;
+}
+declare const runBatch: (input: BatchInput) => Promise<BatchOutput>;
+//#endregion
+//#region src/batch/loaders.d.ts
+interface LoadedTemplate {
+  module: TemplateModule;
+  contentHash: string;
+}
+declare const loadConfig: (rootDir: string) => Promise<StudioConfig>;
+declare const importTemplateForBatch: (rootDir: string, componentPath: string, templateId: string) => Promise<LoadedTemplate>;
+declare const parseDataFile: (filePath: string) => Promise<Record<string, unknown>[]>;
+declare const resolveLocales: (rootDir: string, localeCodes: string[], templateId: string) => Promise<{
+  id: string;
+  data?: Record<string, unknown>;
+}[]>;
+//#endregion
+export { AppError, type BatchInput, type BatchOutput, type CacheStats, type CompileCacheKeyInput, type CompiledTemplate, type DataRow, ErrorCode, type ErrorCode as ErrorCodeType, type Font, type LoadedTemplate, type LogLevel, type Manifest, type ManifestEntry, type MatrixCell, type MatrixInput, type MatrixLocaleInput, type NamingOptions, type PixelCacheKeyInput, type Preset, PropValidationError, type PropValidationIssue, RenderCache, type RenderCacheOptions, type RenderOneInput, type RenderOneOutput, type RenderOptions, type RenderOutput, type SingleInput, type SingleOutput, type StudioConfig, type TemplateEntry, type TemplateModule, compileTemplate, expandMatrix, generateOutputFilename, importTemplateForBatch, isZodObject, loadConfig, logDebug, logError, logInfo, logWarn, measureTemplate, parseDataFile, registerFont, renderAutoSized, renderComponent, renderOne, renderToPixels, resolveLocales, runBatch, studioConfigSchema, validateProps, writeManifest, zodToJsonSchemaShape };