@vyr/engine 0.0.33 → 0.0.34

package/src/math/Quaternion.ts

@@ -19,7 +19,7 @@ import { Vector3 } from './Vector3';
  * vector.applyQuaternion( quaternion );
  * ```
  */
-class Quaternion {
+export class Quaternion {
     x: number;
     y: number;
     z: number;
@@ -732,6 +732,4 @@ class Quaternion {
         yield this.z;
         yield this.w;
     }
-}
-
-export { Quaternion };
+}

package/src/math/Vector2.ts

@@ -26,7 +26,7 @@ import { clamp } from './utils';
  * const d = a.distanceTo( b );
  * ```
  */
-class Vector2 {
+export class Vector2 {
     static create(v2?: number | DeserializationObject<Vector2>, y?: number) {
         if (v2 === undefined) return new Vector2()
 
@@ -60,6 +60,7 @@ class Vector2 {
 
     /**
      * Alias for {@link Vector2#x}.
+     * @DSL_HIDDEN
      */
     get width(): number {
         return this.x;
@@ -71,6 +72,7 @@ class Vector2 {
 
     /**
      * Alias for {@link Vector2#y}.
+     * @DSL_HIDDEN
      */
     get height(): number {
         return this.y;
@@ -675,6 +677,4 @@ class Vector2 {
         yield this.x;
         yield this.y;
     }
-}
-
-export { Vector2 };
+}

package/src/math/Vector3.ts

@@ -42,7 +42,7 @@ interface Cylindrical {
  * const d = a.distanceTo( b );
  * ```
  */
-class Vector3 {
+export class Vector3 {
     static create(v3?: number | DeserializationObject<Vector3>, y?: number, z?: number) {
         if (v3 === undefined) return new Vector3()
 
@@ -1057,6 +1057,4 @@ class Vector3 {
 
 // 全局辅助变量
 const _vector = /*@__PURE__*/ new Vector3();
-const _quaternion = /*@__PURE__*/ new Quaternion();
-
-export { Vector3 };
+const _quaternion = /*@__PURE__*/ new Quaternion();

package/src/math/utils.ts

@@ -6,12 +6,8 @@
  * @param {number} max - The max value.
  * @return {number} The clamped value.
  */
-function clamp(value: number, min: number, max: number) {
+export function clamp(value: number, min: number, max: number) {
 
     return Math.max(min, Math.min(max, value));
 
-}
-
-export {
-    clamp
 }

package/src/schema/AnimationUnit.ts

@@ -0,0 +1,68 @@
+import z from "zod";
+
+export const NumberFrameDataSchema = z.object({
+    type: z.literal('number').default('number'),
+    startValue: z.number().default(0),
+    endValue: z.number().default(0),
+})
+export type NumberFrameData = z.infer<typeof NumberFrameDataSchema>
+
+export const BooleanFrameDataSchema = z.object({
+    type: z.literal('boolean').default('boolean'),
+    startValue: z.boolean().default(true),
+    endValue: z.boolean().default(true),
+})
+export type BooleanFrameData = z.infer<typeof BooleanFrameDataSchema>
+
+export const Vector2FrameDataSchema = z.object({
+    type: z.literal('vector2').default('vector2'),
+    startValue: z.tuple([z.number(), z.number()]).default([0, 0]),
+    endValue: z.tuple([z.number(), z.number()]).default([0, 0]),
+})
+
+export const Vector3FrameDataSchema = z.object({
+    type: z.literal('vector3').default('vector3'),
+    startValue: z.tuple([z.number(), z.number(), z.number()]).default([0, 0, 0]),
+    endValue: z.tuple([z.number(), z.number(), z.number()]).default([0, 0, 0]),
+})
+
+export const EulerFrameDataSchema = z.object({
+    type: z.literal('euler').default('euler'),
+    startValue: z.tuple([z.number(), z.number(), z.number()]).default([0, 0, 0]),
+    endValue: z.tuple([z.number(), z.number(), z.number()]).default([0, 0, 0]),
+})
+export type VectorFrameData = z.infer<
+    typeof Vector2FrameDataSchema |
+    typeof Vector3FrameDataSchema |
+    typeof EulerFrameDataSchema
+>
+
+export const ColorFrameDataSchema = z.object({
+    type: z.literal('color').default('color'),
+    startValue: z.string().default('#ffffff'),
+    endValue: z.string().default('#ffffff'),
+})
+export type ColorFrameData = z.infer<typeof ColorFrameDataSchema>
+
+/**
+ * 动画帧数据类型联合
+ */
+export type AnimationFrameData = NumberFrameData | BooleanFrameData | VectorFrameData | ColorFrameData
+
+export const parseFrameData = (data: AnimationFrameData) => {
+    switch (data.type) {
+        case 'boolean':
+            return BooleanFrameDataSchema.parse(data)
+        case 'vector2':
+            return Vector2FrameDataSchema.parse(data)
+        case 'vector3':
+            return Vector3FrameDataSchema.parse(data)
+        case 'euler':
+            return EulerFrameDataSchema.parse(data)
+        case 'color':
+            return ColorFrameDataSchema.parse(data)
+        default:
+            return NumberFrameDataSchema.parse(data)
+    }
+}
+

package/src/schema/Asset.ts

@@ -0,0 +1,13 @@
+import z from "zod"
+import { Descriptor } from "../descriptor/Descriptor"
+
+export type JsonAsset = { [k: string]: any }
+export type RawAsset = HTMLImageElement | ImageBitmap | HTMLAudioElement | AudioBuffer | HTMLVideoElement | string | JsonAsset
+export type StaticFactory = (url: string, forced?: boolean) => Promise<any>
+export type DescriptorProvider = () => Promise<Descriptor>
+
+export const AssetPropertySchame = z.object({
+    url: z.string().default('')
+})
+export type AssetProperty = z.infer<typeof AssetPropertySchame>
+export type AssetPropertyCollection<T extends AssetProperty = AssetProperty> = T[]

package/src/schema/Descriptor.ts

@@ -0,0 +1,41 @@
+import z from "zod"
+import { language } from "../locale"
+import { Descriptor } from "../descriptor/Descriptor"
+
+/**描述器祖先节点 */
+export interface DescriptorAncestor<T extends Descriptor = Descriptor> {
+    parent: T | null,
+    uuids: string[]
+    collection: Descriptor[]
+}
+
+/**当前描述器节点的邻接关系 */
+export interface DescriptorAdjacency {
+    /**当前节点的父节点 */
+    parent: string
+    /**当前节点的前一个节点 */
+    prev: string
+    /**当前节点的后一个节点 */
+    next: string
+}
+
+const pathRegex = /^[a-zA-Z_$][a-zA-Z0-9_$]*(\.[a-zA-Z_$][a-zA-Z0-9_$]*|\[\d+\])*$/
+
+const validatePath = (path: string) => {
+    const value = path.trim()
+    return value === '' || pathRegex.test(value)
+}
+
+export const VariabConfigSchema = z.object({
+    type: z.enum(['key', 'custom']).default('key'),
+    enabled: z.boolean().default(false),
+    value: z.string().default('').refine(
+        validatePath,
+        language.get('descriptor.variables.config.value')
+    )
+})
+export type VariabConfig = z.infer<typeof VariabConfigSchema>
+
+export const DescriptorVariablesSchema = z.object().catchall(VariabConfigSchema).default({})
+export type DescriptorVariables = z.infer<typeof DescriptorVariablesSchema>
+

package/src/schema/HTML.ts

@@ -0,0 +1,261 @@
+import z from "zod"
+
+export const PositionEnum = z.enum([
+    'static',
+    'relative',
+    'absolute',
+    'fixed',
+    'sticky'
+])
+export type Position = z.infer<typeof PositionEnum>
+
+export const DisplayEnum = z.enum([
+    'block',
+    'inline',
+    'inline-block',
+    'flex',
+    'inline-flex',
+    'grid',
+    'inline-grid',
+    'contents',
+    'flow-root',
+    'table',
+    'table-row',
+    'table-cell',
+    'list-item'
+])
+export type Display = z.infer<typeof DisplayEnum>
+
+export const HTMLStyleSchema = z.object({
+    position: PositionEnum.default('static'),
+    display: DisplayEnum.default('block'),
+    boxSizing: z.literal('border-box').default('border-box'),
+    width: z.string().default(''),
+    height: z.string().default(''),
+}).catchall(z.string())
+
+/**
+ * HTML元素行内样式定义
+ * 
+ * 用于定义单个HTML节点的私有样式属性，优先级高于共享CSS样式。
+ * 每个属性对应一个CSS样式规则，采用大驼峰命名（CamelCase）。
+ * 
+ * 设计原则：
+ * 1. 行内样式具有最高优先级，会覆盖外部样式表中的相同属性
+ * 2. 适合定义节点特有的样式，避免与共享样式冲突
+ * 3. 对于可复用的样式，建议使用Scene中的共享样式
+ * 4. 样式优先级：行内样式（大驼峰） > 共享样式（kebab-case） > 浏览器默认
+ * 
+ * 强制使用border-box的原因：
+ * - 确保布局行为的一致性和可预测性
+ * - width/height = 内容宽度/高度 + padding + border
+ * - 添加padding或border不会改变元素的实际占用空间
+ * - 简化响应式布局的计算，精确控制尺寸
+ * - 避免组件嵌套时混合盒模型带来的计算复杂度
+ */
+export type HTMLStyle = z.infer<typeof HTMLStyleSchema>
+
+const ClassNamesSchema = z.array(z.string()).default([])
+
+export type ClassNames = z.infer<typeof ClassNamesSchema>
+
+export const HtmlAttributesSchema = z.object({
+    // ========== 基础通用属性 ==========
+    /**
+     * 基础样式属性 - 所有HTML元素通用
+     */
+    style: HTMLStyleSchema,
+
+    /**
+     * CSS类名集合 - 所有HTML元素通用
+     */
+    classNames: ClassNamesSchema,
+
+    // ========== Input 元素属性 ==========
+
+    /**
+     * 输入框类型: text, password, email, number, checkbox, radio, file 等
+     */
+    type: z.string().optional(),
+
+    /**
+     * 输入框的初始值
+     */
+    value: z.union([z.string(), z.number()]).optional(),
+
+    /**
+     * 输入框为空时的提示文本
+     */
+    placeholder: z.string().optional(),
+
+    /**
+     * 是否为必填项
+     */
+    required: z.boolean().optional(),
+
+    /**
+     * 正则表达式验证规则
+     */
+    pattern: z.string().optional(),
+
+    /**
+     * 最大字符数
+     */
+    maxlength: z.number().int().positive().optional(),
+
+    /**
+     * 最小字符数
+     */
+    minlength: z.number().int().positive().optional(),
+
+    /**
+     * 数字/日期的最小允许值
+     */
+    min: z.union([z.number(), z.string()]).optional(),
+
+    /**
+     * 数字/日期的最大允许值
+     */
+    max: z.union([z.number(), z.string()]).optional(),
+
+    /**
+     * 数字/日期的增减步长
+     */
+    step: z.union([z.number(), z.string()]).optional(),
+
+    /**
+     * 是否允许多个值（email/file类型）
+     */
+    multiple: z.boolean().optional(),
+
+    /**
+     * 是否禁用输入框
+     */
+    disabled: z.boolean().optional(),
+
+    /**
+     * 是否只读
+     */
+    readonly: z.boolean().optional(),
+
+    /**
+     * 复选框/单选框的选中状态
+     */
+    checked: z.boolean().optional(),
+
+    /**
+     * 页面加载时自动获得焦点
+     */
+    autofocus: z.boolean().optional(),
+
+    /**
+     * 输入框的显示宽度（字符数）
+     */
+    size: z.number().int().positive().optional(),
+
+    /**
+     * 浏览器自动填充: on/off/具体字段名
+     */
+    autocomplete: z.string().optional(),
+
+    /**
+     * 文件类型限制，如 "image/*", ".pdf,.doc"
+     */
+    accept: z.string().optional(),
+
+    /**
+     * 媒体捕获方式: "environment", "user", true, false
+     */
+    capture: z.union([z.string(), z.boolean()]).optional(),
+}).default({ style: HTMLStyleSchema.parse({}), classNames: ClassNamesSchema.parse([]) })
+
+/**
+ * HTML属性集合
+ * 
+ * 提供结构化的方式定义和管理HTML元素的所有原生属性。
+ * style和classNames为基础通用属性，其余属性按元素类型分类定义。
+ * 
+ * classNames(共享CSS类名列表)
+ * 
+ * 引用在Scene的sharedCSSStyle中定义的共享样式类。
+ * 这些类名应用于当前HTML节点，提供可复用的视觉样式效果。
+ * 
+ * 设计原则：
+ * 1. 使用共享样式类而不是重复定义相同的样式
+ * 2. 组合多个类名实现复杂的视觉效果
+ * 3. 类名中定义的样式可以被行内样式（style）覆盖
+ * 
+ * 工作流程：
+ * 1. 在Scene的sharedCSSStyle中定义共享样式类
+ * 2. 在此属性中引用这些类名
+ * 3. 渲染时自动应用对应的样式规则
+ * 
+ * 特性说明：
+ * - 支持多个类名组合：['theme-primary', 'shadow-large', 'rounded']
+ * - 类名样式可以被行内样式覆盖
+ * - 支持伪类状态（如:hover、:active）
+ * - 支持动画类名引用animations中定义的动画
+ * 
+ * ✅ 正确使用示例：
+ * 1. 应用主题样式：['theme-primary', 'font-heading']
+ * 2. 添加视觉效果：['shadow-medium', 'rounded-corner']
+ * 3. 应用动画效果：['fade-in-animation']
+ * 4. 状态样式组合：['button-base', 'hover-effect', 'active-state']
+ * 
+ * ❌ 错误使用示例：
+ * 1. 直接在此处定义样式字符串（应在sharedCSSStyle中定义）
+ * 2. 包含布局尺寸的类名（布局应由自身的style控制）
+ * 
+ * style(HTML元素行内样式定义)
+ * 
+ * 用于定义单个HTML节点的私有样式属性，优先级高于共享CSS样式。
+ * 每个属性对应一个CSS样式规则，采用大驼峰命名（CamelCase）。
+ * 
+ * 设计原则：
+ * 1. 行内样式具有最高优先级，会覆盖外部样式表中的相同属性
+ * 2. 适合定义节点特有的样式，避免与共享样式冲突
+ * 3. 对于可复用的样式，建议使用Scene中的共享样式
+ * 4. 样式优先级：行内样式（大驼峰） > 共享样式（kebab-case） > 浏览器默认
+ * 
+ * @example
+ * // Scene中定义的共享样式：
+ * sharedCSSStyle: {
+ *   classNames: {
+ *     '.theme-primary': {
+ *       'background-color': '#007bff',
+ *       'color': '#ffffff'
+ *     },
+ *     '.shadow-medium': {
+ *       'box-shadow': '0 4px 8px rgba(0,0,0,0.1)'
+ *     },
+ *     '.fade-in': {
+ *       'animation': 'fade-in 0.5s ease-in-out'
+ *     }
+ *   },
+ *   animations: {
+ *     'fade-in': {
+ *       '0%': { 'opacity': '0' },
+ *       '100%': { 'opacity': '1' }
+ *     }
+ *   }
+ * }
+ * 
+ * // HTML节点中定义HTML属性集合
+ * htmlAttributes: {
+ *   // 与行内样式组合使用（行内样式优先级更高）：
+ *   classNames: ['theme-primary'], // 共享背景色和文字颜色
+ *   style: { margin: '8px 0' },
+ *   
+ *   // Input元素特有属性
+ *   type: 'text',
+ *   value: '张三',
+ *   placeholder: '请输入用户名',
+ *   required: true,
+ *   maxlength: 50,
+ *   pattern: '^[a-zA-Z0-9_]+$',
+ *   autocomplete: 'off'
+ * }
+ * 
+ */
+export type HtmlAttributes = z.infer<typeof HtmlAttributesSchema>
+

package/src/schema/Interaction.ts

@@ -0,0 +1,50 @@
+import z from "zod";
+import { Generate } from "../Generate";
+import { scriptableInputSchame } from "../Scriptable";
+import { ConditionScriptable } from "../scripts";
+import { AssetPropertySchame } from './Asset'
+
+export const InteractionMapperSchame = z.object({
+    source: z.string().default(''),
+    target: z.string().default(''),
+})
+export type InteractionMapper = z.infer<typeof InteractionMapperSchame>
+export const InteractionMapperArraySchame = z.array(InteractionMapperSchame)
+export type InteractionMapperArray = z.infer<typeof InteractionMapperArraySchame>
+
+export const BaseInteractionNodeSchame = z.object({
+    id: z.string().default(Generate.uuid()),
+    label: z.string().default(''),
+    position: z.object({ x: z.number(), y: z.number() }),
+})
+export const InteractionExecuteNodeSchame = BaseInteractionNodeSchame.extend({
+    type: z.literal('Execute').default('Execute'),
+    script: z.string().default(''),
+    input: scriptableInputSchame,
+})
+export const InteractionConditionNodeSchame = BaseInteractionNodeSchame.extend({
+    type: z.literal('Condition').default('Condition'),
+    script: z.literal('condition').default('condition'),
+    input: ConditionScriptable.inputSchame,
+})
+export const InteractionNodeSchame = z.union([
+    InteractionExecuteNodeSchame,
+    InteractionConditionNodeSchame
+])
+export type InteractionNode = z.infer<typeof InteractionNodeSchame>
+
+export const InteractionNodeArraySchame = z.array(InteractionNodeSchame).default([])
+export type InteractionNodeArray = z.infer<typeof InteractionNodeArraySchame>
+
+export const InteractionNodeInputCollectionSchame = z.object().catchall(scriptableInputSchame).default({})
+export type InteractionNodeInputCollection = z.infer<typeof InteractionNodeInputCollectionSchame>
+
+export const InteractionPropertySchame = AssetPropertySchame.extend({
+    uuid: z.string().default(''),
+    type: z.string().default(''),
+    nodes: InteractionNodeInputCollectionSchame,
+})
+export type InteractionProperty = z.infer<typeof InteractionPropertySchame>
+
+export const InteractionPropertyArraySchame = z.array(InteractionPropertySchame).default([])
+export type InteractionPropertyArray = z.infer<typeof InteractionPropertyArraySchame>

package/src/schema/Scene.ts

@@ -0,0 +1,138 @@
+import { z } from 'zod';
+import { language } from '../locale';
+
+/**
+ * 验证CSS属性名格式（连字符格式）
+ * 例如：'background-color', 'font-size', 'border-radius'
+ */
+export const CssPropertyNameSchema = z.string().regex(
+    /^[a-zA-Z][a-zA-Z0-9-]*$/,
+    language.get('scene.cssPropertyName.invalid')
+);
+
+/**
+ * 验证CSS属性值格式
+ * 不允许为空字符串，且不能包含 potentially dangerous 内容
+ */
+export const CssPropertyValueSchema = z.string().min(1, language.get('scene.cssPropertyValue.empty')).refine(
+    (val) => !val.includes('<') && !val.includes('>') && !val.includes('javascript:'),
+    language.get('scene.cssPropertyValue.unsafe')
+);
+
+/**
+ * CSS样式属性对象模式
+ * 键为CSS属性名（连字符格式），值为属性值的字符串
+ */
+export const CssPropertyObjectSchema = z.record(
+    CssPropertyNameSchema,
+    CssPropertyValueSchema
+).refine(
+    (obj) => Object.keys(obj).length > 0,
+    language.get('scene.cssPropertyObject.empty')
+);
+
+/**
+ * 验证CSS选择器格式
+ * 支持基本的选择器类型：类选择器、ID选择器、元素选择器、伪类、组合选择器
+ */
+export const CssSelectorSchema = z.string().regex(
+    /^[.#]?[a-zA-Z][a-zA-Z0-9_-]*(?::[a-zA-Z-]+)?(?:[ >+~][.#]?[a-zA-Z][a-zA-Z0-9_-]*(?::[a-zA-Z-]+)?)*$/,
+    language.get('scene.cssSelector.invalid')
+).refine(
+    (selector) => selector.trim().length > 0,
+    language.get('scene.cssSelector.empty')
+);
+
+/**
+ * CSS类选择器样式定义模式
+ * 键为CSS选择器字符串，值为对应的样式规则对象
+ */
+export const ClassNamesSchema = z.record(
+    CssSelectorSchema,
+    CssPropertyObjectSchema
+)
+
+/**
+ * 验证关键帧百分比格式
+ * 支持：0% - 100%，以及 from/to 关键字
+ */
+export const KeyframePercentageSchema = z.string().refine(
+    (val) => {
+        if (val === 'from' || val === 'to') return true;
+        const percentage = parseInt(val);
+        return /^\d{1,2}%$|^100%$/.test(val) && percentage >= 0 && percentage <= 100;
+    },
+    language.get('scene.keyframe.invalid')
+);
+
+/**
+ * CSS关键帧动画定义模式
+ * 键为动画名称，值为包含关键帧百分比和对应样式规则的对象
+ */
+export const AnimationsSchema = z.record(
+    z.string().regex(
+        /^[a-zA-Z][a-zA-Z0-9_-]*$/,
+        language.get('scene.animation.name.invalid')
+    ),
+    z.record(
+        KeyframePercentageSchema,
+        CssPropertyObjectSchema
+    ).refine(
+        (obj) => {
+            const keys = Object.keys(obj);
+            return keys.length >= 2 && (keys.includes('from') || keys.includes('0%')) && (keys.includes('to') || keys.includes('100%'));
+        },
+        language.get('scene.animation.missingStartEnd')
+    )
+)
+
+export const SharedCSSStyleSchema = z.object({
+    classNames: ClassNamesSchema.optional().default({}),
+    animations: AnimationsSchema.optional().default({}),
+})
+
+/**
+ * 共享CSS样式
+ * 
+ * 提供对HTML节点的样式自定义能力，支持CSS类名样式定义和关键帧动画。
+ * 所有样式定义遵循标准CSS语法规则，但使用JavaScript对象表示法。
+ * 
+ * 核心设计原则：
+ * 这里定义的样式应该是影响多个节点的共享样式，即可被多个HTML节点共用的className。
+ * 这些样式通常定义的是视觉表现而非布局，如颜色、字体、动画等公共视觉效果。
+ * 
+ * ✅ 正确使用示例（共享样式）：
+ * 1. 主题颜色类: `.primary-color`, `.secondary-color`
+ * 2. 字体样式类: `.heading-font`, `.body-text`
+ * 3. 动画效果类: `.fade-in`, `.slide-up`
+ * 4. 状态样式类: `.disabled`, `.active-state`
+ * 5. 通用效果类: `.shadow`, `.rounded-corners`
+ * 
+ * ❌ 错误使用示例（避免使用的样式）：
+ * 1. 布局相关: 如 `width: '100px'`, `height: '50px'`, `position: 'absolute'`
+ * 2. 位置相关: 如 `top: '10px'`, `left: '20px'`, `margin: '15px'`
+ * 3. 尺寸相关: 如 `min-width: '200px'`, `max-height: '300px'`
+ * 4. 节点特定的布局属性（这些应由节点的transform控制）
+ * 
+ * @example
+ * const sharedStyles = {
+ *   classNames: {
+ *     '.theme-primary': {
+ *       'background-color': '#007bff',
+ *       'color': '#ffffff'
+ *     },
+ *     '.hover-lift:hover': {
+ *       'transform': 'translateY(-2px)',
+ *       'shadow': '0 4px 12px rgba(0,0,0,0.15)'
+ *     }
+ *   },
+ *   animations: {
+ *     'fade-in': {
+ *       '0%': { 'opacity': '0', 'transform': 'translateY(10px)' },
+ *       '100%': { 'opacity': '1', 'transform': 'translateY(0)' }
+ *     }
+ *   }
+ * };
+ */
+export type SharedCSSStyle = z.infer<typeof SharedCSSStyleSchema>;
+

package/src/schema/Store.ts

@@ -0,0 +1,8 @@
+import z from "zod";
+
+export const StoreDataSchema = z.union([
+    z.object().catchall(z.any()),
+    z.array(z.any()),
+]).default({})
+
+export type StoreData = z.infer<typeof StoreDataSchema>

package/src/schema/index.ts

@@ -0,0 +1,7 @@
+export * from './Asset'
+export * from './Descriptor'
+export * from './Store'
+export * from './Interaction'
+export * from './HTML'
+export * from './AnimationUnit'
+export * from './Scene'