@bardway/trpg-pixi 0.0.0-stage → 0.1.0

package/dist/recipes/EffectPrimitiveRuntimeRegistry.d.ts

@@ -0,0 +1,28 @@
+import type { EffectPrimitiveDescriptor } from './primitives.js';
+import type { EffectRecipeDefinition, EffectRecipeId, EffectRecipeTrackDefinition, ResolvedRecipeValue } from './schema.js';
+export type EffectPrimitiveResolvedParams = Record<string, ResolvedRecipeValue>;
+export interface EffectPrimitiveRuntimeHandle {
+    cleanup(): void;
+    completed?: Promise<void>;
+    cleanupPolicy?: 'track-end' | 'recipe-end';
+}
+export type EffectPrimitiveCleanup = void | (() => void) | EffectPrimitiveRuntimeHandle;
+export type EffectPrimitiveExecuteResult = EffectPrimitiveCleanup | Promise<EffectPrimitiveCleanup>;
+export interface EffectPrimitiveExecutionContext<TRuntimeContext = unknown> {
+    recipeId: EffectRecipeId;
+    recipe: EffectRecipeDefinition;
+    track: EffectRecipeTrackDefinition;
+    primitive: EffectPrimitiveDescriptor;
+    runtimeContext: TRuntimeContext;
+}
+export interface EffectPrimitiveRuntime<TRuntimeContext = unknown> {
+    readonly primitiveId: string;
+    readonly consumedParams?: readonly string[];
+    execute(context: EffectPrimitiveExecutionContext<TRuntimeContext>, params: EffectPrimitiveResolvedParams, signal: AbortSignal): EffectPrimitiveExecuteResult;
+}
+export declare class EffectPrimitiveRuntimeRegistry<TRuntimeContext = unknown> {
+    private readonly runtimes;
+    register(runtime: EffectPrimitiveRuntime<TRuntimeContext>): void;
+    get(primitiveId: string): EffectPrimitiveRuntime<TRuntimeContext> | null;
+    listIds(): readonly string[];
+}

package/dist/recipes/EffectRecipeExecutor.d.ts

@@ -0,0 +1,73 @@
+import { type EffectPrimitiveDescriptor, type EffectPrimitiveRegistry } from './primitives.js';
+import { type EffectRecipeRegistry } from './registry.js';
+import { type EffectRecipeValidationError, type EffectRecipeDefinition, type EffectRecipeId, type EffectRecipeTrackDefinition, type EffectRecipeTuningPathReference, type ResolvedRecipeValue } from './schema.js';
+import type { EffectPrimitiveExecutionContext, EffectPrimitiveResolvedParams, EffectPrimitiveRuntime } from './EffectPrimitiveRuntimeRegistry.js';
+import { EffectPrimitiveRuntimeRegistry } from './EffectPrimitiveRuntimeRegistry.js';
+export type EffectRecipeExecutorErrorCode = 'invalid_params' | 'runtime_error' | 'tuning_resolution_failed' | 'unknown_primitive' | 'unknown_recipe' | 'unknown_runtime';
+export interface EffectRecipeExecutorScheduler {
+    setTimeout(callback: () => void, delayMs: number): unknown;
+    clearTimeout(handle: unknown): void;
+}
+export interface EffectRecipeTuningResolutionContext<TRuntimeContext> {
+    recipe: EffectRecipeDefinition;
+    track: EffectRecipeTrackDefinition;
+    primitive: EffectPrimitiveDescriptor;
+    paramName: string;
+    runtimeContext: TRuntimeContext;
+}
+export interface EffectRecipeTrackPlanItem<TRuntimeContext> {
+    track: EffectRecipeTrackDefinition;
+    primitive: EffectPrimitiveDescriptor;
+    runtime: EffectPrimitiveRuntime<TRuntimeContext>;
+    params: EffectPrimitiveResolvedParams;
+    executionContext: EffectPrimitiveExecutionContext<TRuntimeContext>;
+}
+export interface EffectRecipeExecutionOutcome {
+    recipeId: EffectRecipeId;
+    status: 'completed' | 'aborted';
+    committed: boolean;
+}
+export interface EffectRecipeExecutionHandle {
+    recipe: EffectRecipeDefinition;
+    signal: AbortSignal;
+    done: Promise<EffectRecipeExecutionOutcome>;
+    abort(reason?: string): void;
+}
+export interface EffectRecipeExecutorOptions<TRuntimeContext> {
+    runtimeRegistry: EffectPrimitiveRuntimeRegistry<TRuntimeContext>;
+    resolveTuningPath: (reference: EffectRecipeTuningPathReference, context: EffectRecipeTuningResolutionContext<TRuntimeContext>) => ResolvedRecipeValue;
+    scheduler: EffectRecipeExecutorScheduler;
+    recipeRegistry: Pick<EffectRecipeRegistry, 'get' | 'validate'>;
+    primitiveRegistry: EffectPrimitiveRegistry;
+}
+export interface ExecuteEffectRecipeOptions<TRuntimeContext> {
+    recipe: EffectRecipeId | EffectRecipeDefinition;
+    runtimeContext: TRuntimeContext;
+    signal?: AbortSignal;
+    onCommit?: (recipe: EffectRecipeDefinition) => void;
+    onDone?: (outcome: EffectRecipeExecutionOutcome) => void;
+}
+export declare class EffectRecipeExecutorError extends Error {
+    readonly code: EffectRecipeExecutorErrorCode;
+    readonly recipeId: EffectRecipeId;
+    readonly cause: unknown;
+    constructor(code: EffectRecipeExecutorErrorCode, recipeId: EffectRecipeId, message: string, options?: {
+        trackId?: string;
+        validationErrors?: readonly EffectRecipeValidationError[];
+        cause?: unknown;
+    });
+    readonly trackId?: string;
+    readonly validationErrors: readonly EffectRecipeValidationError[];
+}
+export declare class EffectRecipeExecutor<TRuntimeContext = unknown> {
+    private readonly options;
+    private readonly scheduler;
+    private readonly recipeRegistry;
+    private readonly primitiveRegistry;
+    constructor(options: EffectRecipeExecutorOptions<TRuntimeContext>);
+    buildPlan(recipeInput: EffectRecipeId | EffectRecipeDefinition, runtimeContext: TRuntimeContext): readonly EffectRecipeTrackPlanItem<TRuntimeContext>[];
+    execute(runOptions: ExecuteEffectRecipeOptions<TRuntimeContext>): EffectRecipeExecutionHandle;
+    private resolveRecipe;
+    private resolveTrackPlanItem;
+    private resolveTuningReference;
+}

package/dist/recipes/primitives.d.ts

@@ -0,0 +1,39 @@
+import type { EffectRecipeScope } from './schema.js';
+export declare const EFFECT_PRIMITIVE_CATEGORIES: readonly ["content", "screen", "camera", "shader", "particle", "ui", "audio"];
+export declare const EFFECT_PRIMITIVE_PARAM_TYPES: readonly ["string", "number", "boolean", "number[]"];
+export declare const EFFECT_PRIMITIVE_PREVIEW_SUPPORT: readonly ["full", "milestone", "replay-only"];
+export type EffectPrimitiveCategory = (typeof EFFECT_PRIMITIVE_CATEGORIES)[number];
+export type EffectPrimitiveParamType = (typeof EFFECT_PRIMITIVE_PARAM_TYPES)[number];
+export type EffectPrimitivePreviewSupport = (typeof EFFECT_PRIMITIVE_PREVIEW_SUPPORT)[number];
+export interface EffectPrimitiveParamDescriptor {
+    name: string;
+    label: string;
+    type: EffectPrimitiveParamType;
+    required: boolean;
+    min?: number;
+    max?: number;
+    minLength?: number;
+    maxLength?: number;
+    arrayMinLength?: number;
+    arrayMaxLength?: number;
+    options?: readonly (string | number | boolean)[];
+    tuningPathAllowed?: boolean;
+}
+export interface EffectPrimitiveDescriptor {
+    id: string;
+    label: string;
+    category: EffectPrimitiveCategory;
+    scopes: readonly EffectRecipeScope[];
+    paramsSchema: readonly EffectPrimitiveParamDescriptor[];
+    previewSupport: EffectPrimitivePreviewSupport;
+    conflicts: readonly string[];
+    maxInstances: number;
+}
+export declare class EffectPrimitiveRegistry {
+    private readonly descriptors;
+    private readonly descriptorById;
+    constructor(descriptors: readonly EffectPrimitiveDescriptor[]);
+    all(): readonly EffectPrimitiveDescriptor[];
+    get(id: string): EffectPrimitiveDescriptor | null;
+    listByScope(scope: EffectRecipeScope): readonly EffectPrimitiveDescriptor[];
+}

package/dist/recipes/registry.d.ts

@@ -0,0 +1,57 @@
+import { type EffectPrimitiveDescriptor, type EffectPrimitiveRegistry } from './primitives.js';
+import { type EffectRecipeAppMetadata, type EffectRecipeCategory, type EffectRecipeDefinition, type EffectRecipeId, type EffectRecipeScope, type EffectRecipeTuningPathReference, type EffectRecipeValidationError, type RecipeValue, type ResolvedRecipeValue } from './schema.js';
+export type EffectRecipeSource = 'builtin' | 'custom';
+export interface EffectRecipeManifestEntry {
+    source: EffectRecipeSource;
+    definition: unknown;
+}
+export interface EffectRecipeCatalogEntry {
+    id: EffectRecipeId;
+    name: string;
+    description: string;
+    scope: EffectRecipeScope;
+    category: EffectRecipeCategory;
+    durationMs: number;
+    commitAtMs: number;
+    source: EffectRecipeSource;
+    app: EffectRecipeAppMetadata;
+    trackCount: number;
+}
+export interface EffectRecipeRegistration {
+    source: EffectRecipeSource;
+    definition: EffectRecipeDefinition;
+    catalog: EffectRecipeCatalogEntry;
+}
+export interface EffectRecipeManifestValidationResult {
+    entries: readonly EffectRecipeRegistration[];
+    errors: readonly EffectRecipeValidationError[];
+}
+export interface EffectRecipeSingleValidationResult {
+    entry: EffectRecipeRegistration | null;
+    errors: readonly EffectRecipeValidationError[];
+}
+export declare class EffectRecipeRegistryError extends Error {
+    readonly errors: readonly EffectRecipeValidationError[];
+    constructor(errors: readonly EffectRecipeValidationError[]);
+}
+type PrimitiveParamValidationResult<TValue> = {
+    params: Record<string, TValue> | null;
+    errors: readonly EffectRecipeValidationError[];
+};
+export declare const validateEffectRecipeTrackParams: (descriptor: EffectPrimitiveDescriptor, params: unknown, pathPrefix?: string) => PrimitiveParamValidationResult<RecipeValue>;
+export declare const validateResolvedEffectRecipeTrackParams: (descriptor: EffectPrimitiveDescriptor, params: unknown, pathPrefix?: string) => PrimitiveParamValidationResult<ResolvedRecipeValue>;
+export declare const validateEffectRecipeManifest: (entries: readonly EffectRecipeManifestEntry[], primitiveRegistry: EffectPrimitiveRegistry) => EffectRecipeManifestValidationResult;
+export declare class EffectRecipeRegistry {
+    private readonly primitiveRegistry;
+    private readonly entries;
+    private readonly entryById;
+    constructor(manifestEntries: readonly EffectRecipeManifestEntry[], primitiveRegistry: EffectPrimitiveRegistry);
+    all(): readonly EffectRecipeRegistration[];
+    catalog(): readonly EffectRecipeCatalogEntry[];
+    get(recipeId: EffectRecipeId): EffectRecipeRegistration | null;
+    listByScope(scope: EffectRecipeScope): readonly EffectRecipeRegistration[];
+    listByCategory(category: EffectRecipeCategory): readonly EffectRecipeRegistration[];
+    validate(definition: unknown, source?: EffectRecipeSource): EffectRecipeSingleValidationResult;
+}
+export declare const resolveEffectRecipePrimitiveDescriptor: (recipe: EffectRecipeDefinition, trackIndex: number, primitiveRegistry: EffectPrimitiveRegistry) => EffectPrimitiveDescriptor | null;
+export type { EffectRecipeTuningPathReference };

package/dist/recipes/schema.d.ts

@@ -0,0 +1,93 @@
+export declare const EFFECT_RECIPE_SCHEMA_VERSION = 4;
+export declare const EFFECT_RECIPE_SCOPES: readonly ["story", "battle"];
+export declare const EFFECT_RECIPE_CATEGORIES: readonly ["entrance", "utility"];
+export declare const EFFECT_RECIPE_ID_MAX_LENGTH = 80;
+export declare const EFFECT_RECIPE_TRACK_ID_MAX_LENGTH = 80;
+export declare const EFFECT_RECIPE_PRIMITIVE_ID_MAX_LENGTH = 80;
+export declare const EFFECT_RECIPE_NAME_MAX_CODE_POINTS = 80;
+export declare const EFFECT_RECIPE_DESCRIPTION_MAX_CODE_POINTS = 240;
+export declare const EFFECT_RECIPE_APP_LABEL_MAX_CODE_POINTS = 48;
+export declare const EFFECT_RECIPE_APP_SHORT_DESCRIPTION_MAX_CODE_POINTS = 120;
+export declare const EFFECT_RECIPE_APP_ICON_ID_MAX_LENGTH = 80;
+export declare const EFFECT_RECIPE_MAX_DURATION_MS = 20000;
+export declare const EFFECT_RECIPE_MAX_TRACKS = 24;
+export declare const EFFECT_RECIPE_VALUE_MAX_STRING_CODE_POINTS = 240;
+export declare const EFFECT_RECIPE_VALUE_MAX_ARRAY_LENGTH = 8;
+export declare const EFFECT_RECIPE_TUNING_PATH_MAX_LENGTH = 160;
+export declare const EFFECT_RECIPE_APP_ORDER_MAX = 9999;
+export declare const EFFECT_RECIPE_STABLE_ID_REGEX: RegExp;
+export declare const EFFECT_RECIPE_TUNING_PATH_REGEX: RegExp;
+export type EffectRecipeScope = (typeof EFFECT_RECIPE_SCOPES)[number];
+export type EffectRecipeCategory = (typeof EFFECT_RECIPE_CATEGORIES)[number];
+export type EffectRecipeId = string;
+export type EffectRecipeTrackId = string;
+export type EffectPrimitiveId = string;
+export interface EffectRecipeTuningPathReference {
+    tuningPath: string;
+}
+export type RecipeValue = string | number | boolean | number[] | EffectRecipeTuningPathReference;
+export type ResolvedRecipeValue = string | number | boolean | number[];
+export interface EffectRecipeAppMetadata {
+    label: string;
+    shortDescription: string;
+    iconId: string;
+    order: number;
+}
+export declare const EFFECT_TARGETS: readonly ["main-content", "story-workspace", "full-stage"];
+export type EffectTarget = (typeof EFFECT_TARGETS)[number];
+export interface EffectRecipeTrackDefinition {
+    target?: EffectTarget;
+    id: EffectRecipeTrackId;
+    atMs: number;
+    durationMs: number;
+    primitiveId: EffectPrimitiveId;
+    params: Record<string, RecipeValue>;
+    enabled: boolean;
+}
+export interface EffectRecipeDefinition {
+    schemaVersion: typeof EFFECT_RECIPE_SCHEMA_VERSION;
+    id: EffectRecipeId;
+    name: string;
+    description: string;
+    scope: EffectRecipeScope;
+    category: EffectRecipeCategory;
+    durationMs: number;
+    commitAtMs: number;
+    app: EffectRecipeAppMetadata;
+    tracks: readonly EffectRecipeTrackDefinition[];
+}
+export type EffectRecipeManifestDocument = Readonly<Record<string, unknown>>;
+export type EffectRecipeValidationErrorCode = 'duplicate_recipe_id' | 'duplicate_track_id' | 'invalid_enum' | 'invalid_id' | 'invalid_length' | 'invalid_param_type' | 'invalid_param_value' | 'invalid_recipe_value' | 'invalid_schema_version' | 'invalid_tuning_path' | 'invalid_type' | 'missing_param' | 'out_of_range' | 'too_many_items' | 'unknown_param' | 'unknown_primitive' | 'unknown_schema_version' | 'unsupported_scope';
+export interface EffectRecipeValidationError {
+    code: EffectRecipeValidationErrorCode;
+    path: string;
+    message: string;
+}
+export interface EffectRecipeMigration {
+    schemaVersion: number;
+    migrate(definition: EffectRecipeManifestDocument): unknown;
+}
+export interface EffectRecipeMigrationResult {
+    document: EffectRecipeManifestDocument | null;
+    errors: readonly EffectRecipeValidationError[];
+}
+export interface EffectRecipeDefinitionValidationResult {
+    definition: EffectRecipeDefinition | null;
+    errors: readonly EffectRecipeValidationError[];
+}
+export declare const EFFECT_RECIPE_MIGRATIONS: readonly [EffectRecipeMigration];
+export declare const effectRecipeMigrationRegistry: Readonly<{
+    all: () => readonly EffectRecipeMigration[];
+    get: (schemaVersion: number) => EffectRecipeMigration | null;
+}>;
+export declare const isEffectRecipeScope: (value: unknown) => value is EffectRecipeScope;
+export declare const isEffectRecipeCategory: (value: unknown) => value is EffectRecipeCategory;
+export declare const isEffectRecipeId: (value: unknown) => value is EffectRecipeId;
+export declare const isEffectRecipeTrackId: (value: unknown) => value is EffectRecipeTrackId;
+export declare const isEffectPrimitiveId: (value: unknown) => value is EffectPrimitiveId;
+export declare const isEffectRecipeTuningPath: (value: unknown) => value is string;
+export declare const isEffectRecipeTuningPathReference: (value: unknown) => value is EffectRecipeTuningPathReference;
+export declare const isResolvedRecipeValue: (value: unknown) => value is ResolvedRecipeValue;
+export declare const migrateEffectRecipeDefinition: (value: unknown) => EffectRecipeMigrationResult;
+export declare const validateEffectRecipeDefinition: (value: unknown) => EffectRecipeDefinitionValidationResult;
+export declare const createEffectRecipeValidationError: (code: EffectRecipeValidationErrorCode, path: string, message: string) => EffectRecipeValidationError;

package/dist/recipes.d.ts

@@ -0,0 +1,5 @@
+export * from './recipes/schema.js';
+export * from './recipes/primitives.js';
+export * from './recipes/registry.js';
+export * from './recipes/EffectPrimitiveRuntimeRegistry.js';
+export * from './recipes/EffectRecipeExecutor.js';