@zcomponent/core 2.0.0-alpha.4 → 2.0.0-alpha.5

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zcomponent/core",
-	"version": "2.0.0-alpha.4",
+	"version": "2.0.0-alpha.5",
 	"description": "The core component model and built-in functionality for Mattercraft.",
 	"author": "Zappar Limited",
 	"license": "Proprietary",
@@ -39,6 +39,7 @@
 	"files": [
 		"index.js",
 		"index.d.ts",
+		"prompt.md",
 		"lib/**/*",
 		"css/**/*",
 		"assets/**/*"

package/prompt.md

@@ -0,0 +1,611 @@
+# Scripting
+
+## Component and Behavior Registration
+
+Components and behaviors are registered using class decorators that provide metadata to the Mattercraft editor:
+
+```typescript
+@zComponent({
+	icon: 'music_note',
+	group: 'Media',
+	tags: ['core/audio'],
+})
+export class Audio extends Component<undefined, AudioConstructorProps> {
+	// Component implementation
+}
+```
+
+```typescript
+@zBehavior({
+	icon: 'volume_up',
+	group: BehaviorGroups.Actions,
+	runAtDesignTime: true,
+})
+export class PlaySound extends ActionBehavior<PlaySoundProps> {
+	// Behavior implementation
+}
+```
+
+**Registration Options:**
+
+- `icon`: Material Design icon name for the component/behavior
+- `group`: Category grouping in the Mattercraft UI
+- `tags`: Array of tags for search and categorization
+- `parents`: Array of parent tags or glob patterns that limit where the entity can be created
+- `runAtDesignTime`: (Behaviors only) Whether to execute in the editor
+
+## Property Configuration with Decorators
+
+### @zUI() - UI Customization and Actions
+
+Public properties are visible in the Mattercraft UI by default. Use `@zUI()` to customize how a property is presented, or to expose an event or method as a UI action:
+
+```typescript
+public volume = 1;
+
+@zUI({ group: 'Audio', priority: 20, type: 'proportion' })
+public gain = 0.8;
+
+@zUI()
+public play() {
+	// Play implementation
+}
+```
+
+**Configuration Options:**
+
+- `group`: Groups properties under a header in the UI
+- `priority`: Determines display order (higher values appear first)
+- `type`: Specifies the UI widget type
+- `values`: Constrains values to specific types (see Values section)
+
+### @zObserve() - Change Handling
+
+The `@zObserve()` decorator creates change handlers for properties:
+
+```typescript
+@zUI({ group: 'Audio' })
+@zObserve((value, instance) => {
+    instance._updateVolume();
+})
+public volume = 1;
+```
+
+**Observer patterns:**
+
+Simple observers:
+
+```typescript
+@zObserve((v, instance: Audio) => {
+    instance._updateVolume();
+})
+public muted = false;
+```
+
+Context-aware observers:
+
+```typescript
+@zObserve((v, instance) =>
+    instance.contextManager.get(AudioContextContext).setVolumeForLayer(instance.constructorProps?.layer, v)
+)
+public volume = 1;
+```
+
+### @zIgnore() - Serialization and UI Control
+
+Excludes a public property from serialization and the Mattercraft UI. Use it for internal state that should not be user-editable:
+
+```typescript
+@zIgnore()
+public element: HTMLElement;
+```
+
+### @zLoad() - Async Loading
+
+Marks methods as loadable processes that should complete before the experience starts:
+
+```typescript
+@zLoad()
+private async _load() {
+    const response = await fetch(this.constructorProps?.source);
+    this.data = await response.arrayBuffer();
+}
+```
+
+### @zRegister() - Event Registration
+
+Registers methods to listen to events:
+
+```typescript
+const someEvent = new Event<[number]>();
+
+@zRegister(someEvent)
+private _handleChange(value: number) {
+	// Handle event
+}
+```
+
+The first argument can be an `Event` instance, an event property on this entity (for example, `@zRegister('onStateChange')`), or a context class followed by one of its event property names.
+
+The string form resolves a property on the decorated entity itself. It does not resolve a behavior's attached component through `this.instance`. For an event on `this.instance` or another component selected at runtime, use `this.register(component.onEvent, handler)`; use the same managed-listener form for `Observable` values.
+
+## Lifecycle Decorators
+
+### @zOnStart() - Auto-Start Methods
+
+Calls methods when the experience starts:
+
+```typescript
+@zOnStart()
+private _initializeAudio() {
+    // Initialize audio when experience starts
+}
+```
+
+### @zOnConstructed() - Auto-Construction Methods
+
+Calls methods when construction completes:
+
+```typescript
+@zOnConstructed()
+private _setupInitialState() {
+    // Setup after construction
+}
+```
+
+### @zOnLaunch() - Auto-Launch Methods
+
+Calls methods when the experience launches:
+
+```typescript
+@zOnLaunch()
+private _requestPermissions() {
+    // Request permissions when user launches
+}
+```
+
+## Environment Condition Decorators
+
+### @zOnlyRuntime() - Runtime-Only Methods
+
+Methods only execute during runtime (not in editor):
+
+```typescript
+@zOnlyRuntime()
+public startGame() {
+    // Only runs for end users
+}
+```
+
+### @zOnlyDesignTime() - Design-Time-Only Methods
+
+Methods only execute in the Mattercraft editor:
+
+```typescript
+@zOnlyDesignTime()
+public previewEffect() {
+    // Only runs in editor
+}
+```
+
+### @zOnlyEditTime() - Edit-Time-Only Methods
+
+Methods only execute during edit time:
+
+```typescript
+@zOnlyEditTime()
+public validateSettings() {
+    // Only runs during editing
+}
+```
+
+### @zOnlyProduction() - Production-Only Methods
+
+Methods only execute in production builds:
+
+```typescript
+@zOnlyProduction()
+public enableAnalytics() {
+    // Only runs in production
+}
+```
+
+### @zOnlyDevelopment() - Development-Only Methods
+
+Methods only execute in development builds:
+
+```typescript
+@zOnlyDevelopment()
+public enableDebugMode() {
+    // Only runs in development
+}
+```
+
+## Rendering Event Decorators
+
+### @zOnBeforeRender() - Before Render Methods
+
+Registers methods for before render events:
+
+```typescript
+@zOnBeforeRender()
+private _updateAnimation(deltaTime: number) {
+    // Called every frame before rendering
+}
+```
+
+### @zOnAfterRender() - After Render Methods
+
+Registers methods for after render events:
+
+```typescript
+@zOnAfterRender()
+private _updateUI(deltaTime: number) {
+    // Called every frame after rendering
+}
+```
+
+## Analytics Decorators
+
+### @zLogEvent() - Analytics Logging
+
+Logs analytics events when methods are called:
+
+```typescript
+@zLogEvent('button_clicked')
+public handleButtonClick() {
+    // Analytics event logged
+}
+```
+
+## UI Type System
+
+### Built-in UI Types
+
+The `type` option in `@zUI()` configures the UI widget:
+
+**Numeric inputs:**
+
+- `proportion`: 0-1 range with slider input
+- `time-seconds`, `time-milliseconds`: Time inputs with unit conversion
+- `angle-radians`, `angle-degrees`: Angle inputs with unit conversion
+
+**Color inputs:**
+
+- `color-hex`: Hex color picker (`#FF0000`)
+- `color-norm-rgb`, `color-norm-rgba`: Normalized RGB/RGBA arrays (0-1)
+- `color-unnorm-rgb`, `color-unnorm-rgba`: Unnormalized RGB/RGBA arrays (0-255)
+
+**Text inputs:**
+
+- `text-multiline`: Textarea for multiline text
+
+**Function types:**
+
+- `function-emit-component-prop-event`: Event emission function
+
+### Value Constraints
+
+The `values` option constrains property values:
+
+```typescript
+@zUI({ values: 'layerclipids' })
+public state?: string;
+
+@zUI({ values: 'streamids' })
+public stream?: string;
+
+@zUI({ values: 'easings' })
+public easing: Easing = 'linear';
+```
+
+**Available value types:**
+
+- `layerclipids`: Timeline/state IDs in the scene
+- `layerids`: Layer IDs in the scene
+- `streamids`: Available stream IDs
+- `easings`: Animation easing functions
+- `nodeids`: Scene node IDs
+- `nodelabels`: Scene node labels
+- `animations`: Animation names in the file-in-context
+- `morphtargets`: Morph target names in the file-in-context
+- `events`: Component events annotated with @zUI
+
+## Constructor Props and Type System
+
+Constructor props use TypeScript types to configure the UI. Import specialized types from `@zcomponent/core`:
+
+```typescript
+import { Range, Angle, ProjectFile, Color, Time, Proportion, MultilineText } from '@zcomponent/core';
+
+export interface MyComponentProps {
+	// File selection with glob patterns
+	model: ProjectFile<'*.glb'>;
+	texture: ProjectFile<'*.{png,jpg}'>;
+
+	// Numeric ranges with bounds
+	opacity: Range<0, 1>;
+	volume: Range<0, 100>;
+
+	// Angular values with units
+	rotation: Angle<'degrees'>;
+	phase: Angle<'radians'>;
+
+	// Color values with format
+	background: Color<'hex'>;
+	tint: Color<'norm-rgb'>;
+	overlay: Color<'rgba'>;
+
+	// Time values with units
+	duration: Time<'seconds'>;
+	delay: Time<'milliseconds'>;
+
+	// Proportional values (0-1)
+	progress: Proportion;
+
+	// Text inputs
+	description: MultilineText;
+
+	// Basic types
+	title: string;
+	count: number;
+	enabled: boolean;
+}
+```
+
+**Available Types:**
+
+- `Range<MIN, MAX>`: Numeric range with bounds
+- `Angle<'radians' | 'degrees'>`: Angular measurement
+- `ProjectFile<GLOB>`: File path with glob constraint
+- `Color<FORMAT, SPACE>`: Color value with format/space
+- `Time<'seconds' | 'milliseconds' | 'hertz'>`: Time duration
+- `Proportion`: 0-1 range value
+- `MultilineText`: Multiline text content
+- `Url`: URL string
+- `EmailAddress`: Email with validation
+
+## Events
+
+Events are type-safe and exposed to the UI with `@zUI()`:
+
+```typescript
+@zUI()
+public readonly onEnded = new Event<[Audio]>();
+
+@zUI()
+public readonly onSave = new Event();
+```
+
+Emit events with arguments:
+
+```typescript
+this.onEnded.emit(this);
+```
+
+Register event handlers:
+
+```typescript
+this.register(otherComponent.onEnded, audio => {
+	// Handle audio end event
+});
+```
+
+## Methods as UI Actions
+
+Methods can be exposed as actions in the UI:
+
+```typescript
+@zUI()
+public play(opts?: PlayOptions) {
+    // Play implementation
+}
+
+@zUI()
+public preview() {
+    this.perform();
+}
+
+@zUI({ type: 'time-milliseconds' })
+public seek(t: number) {
+    // Seek implementation
+}
+```
+
+## Property Groups
+
+Group related properties using group objects or strings:
+
+```typescript
+const audioGroup: ZPropGroup = {
+    name: 'Audio',
+    priority: 20,
+};
+
+@zUI({ group: audioGroup })
+public muted = false;
+
+@zUI({ group: 'Settings', priority: 10 })
+public autoplay = true;
+```
+
+## Complete Example
+
+```typescript
+@zComponent({ icon: 'music_note', group: 'Media' })
+export class Audio extends Component<undefined, AudioConstructorProps> {
+	@zUI()
+	public readonly onEnded = new Event<[Audio]>();
+
+	@zUI({ group: 'Audio', priority: 20 })
+	@zObserve((v, instance: Audio) => {
+		instance._updateVolume();
+	})
+	public muted = false;
+
+	@zUI({ group: 'Audio', priority: 20, type: 'proportion' })
+	@zObserve((v, instance: Audio) => {
+		instance._updateVolume();
+	})
+	public volume = 1;
+
+	@zUI()
+	public play() {
+		// Play implementation
+	}
+
+	@zUI({ type: 'time-milliseconds' })
+	public seek(t: number) {
+		// Seek implementation
+	}
+
+	private _updateVolume() {
+		// Volume update logic
+	}
+}
+```
+
+## Contexts
+
+Contexts centralize state across components. Access contexts through the contextManager:
+
+```typescript
+import { CanvasContext } from '@zcomponent/core';
+
+const canvasContext = this.contextManager.get(CanvasContext);
+canvasContext.canvas; // HTMLCanvasElement
+```
+
+## Hooks and Utilities
+
+### Canvas and Rendering Hooks
+
+- `useCanvas(mgr: ContextManager)`: Returns the HTMLCanvasElement
+- `useOverlay(mgr: ContextManager)`: Returns an Observable<HTMLDivElement>
+- `useCanvasSize(mgr: ContextManager)`: Returns canvas size observable
+- `useOnBeforeRender(mgr: ContextManager)`: Frame event before 3D render
+- `useOnAfterRender(mgr: ContextManager)`: Frame event after 3D render
+- `useCanvasToDataURL(mgr: ContextManager)`: Canvas to data URL function
+- `useCanvasToArrayBuffer(mgr: ContextManager)`: Canvas to array buffer function
+
+### Lifecycle Hooks
+
+- `useIsLoaded(mgr: ContextManager)`: Observable indicating if experience is loaded
+- `useIsStarted(mgr: ContextManager)`: Observable indicating if experience is started
+- `useIsConstructed(mgr: ContextManager)`: Observable indicating if experience is constructed
+- `useIsLaunched(mgr: ContextManager)`: Observable indicating if experience is launched
+- `useLoadPercent(mgr: ContextManager)`: Observable with loading progress percentage
+
+### Audio Context Hooks
+
+- `useAudioContext(ctx: ContextManager)`: Returns WebAudio AudioContext
+
+### Analytics Hooks
+
+- `useAnalyticsOnEvent(mgr: ContextManager)`: Analytics event emission hook
+
+### Cookie Consent Hooks
+
+- `useCookieConsentFunctional(mgr: ContextManager)`: Functional cookies consent status
+- `useCookieConsentPerformance(mgr: ContextManager)`: Performance cookies consent status
+- `useCookieConsentMarketing(mgr: ContextManager)`: Marketing cookies consent status
+- `useCookieConsentStatus(mgr: ContextManager)`: Overall cookie consent status
+- `usePerformanceVendors(mgr: ContextManager)`: Registered performance vendors
+- `useMarketingVendors(mgr: ContextManager)`: Registered marketing vendors
+- `useShowCookieSettings(mgr: ContextManager)`: Function to show cookie settings
+
+### Orientation Hooks
+
+- `useOnOrientationChange(mgr: ContextManager)`: Device orientation change events
+
+### Snapshot Hooks
+
+- `useCanvasImage(ctx: ContextManager)`: Canvas image data URL
+- `useShareAPISupported(ctx: ContextManager)`: Whether Share API is supported
+- `useCanShare(ctx: ContextManager)`: Whether canvas can be shared
+- `useCanvasFile(ctx: ContextManager)`: Canvas image as File object
+- `useFileName(ctx: ContextManager)`: File name for snapshots
+- `useText(ctx: ContextManager)`: Share text
+- `useTitle(ctx: ContextManager)`: Share title
+- `useFileType(ctx: ContextManager)`: File type (e.g., 'image/png')
+- `useQuality(ctx: ContextManager)`: Image quality value
+
+### User Event Hooks
+
+- `useOnUserEvent(mgr: ContextManager)`: User interaction events
+
+### Environment Utilities
+
+- `isDesignTime(ctx: ContextManager)`: Returns true in Mattercraft editor
+- `isEditTime(ctx: ContextManager)`: Returns true during edit time
+- `isDevelopmentBuild(ctx: ContextManager)`: Returns true in development
+- `isProductionBuild(ctx: ContextManager)`: Returns true in production
+
+### Orientation Utilities
+
+- `isPortrait(mgr: ContextManager)`: Returns true if device is in portrait
+- `isLandscape(mgr: ContextManager)`: Returns true if device is in landscape
+- `isPortraitSecondary(mgr: ContextManager)`: Returns true if in secondary portrait
+- `isLandscapeSecondary(mgr: ContextManager)`: Returns true if in secondary landscape
+
+### Lifecycle Utilities
+
+- `isLoaded(mgr: ContextManager)`: Returns current loaded state
+- `isStarted(mgr: ContextManager)`: Returns current started state
+- `isConstructed(mgr: ContextManager)`: Returns current constructed state
+- `isLaunched(mgr: ContextManager)`: Returns current launched state
+
+## Lifecycle
+
+Use lifecycle decorators on methods. Keep constructors for synchronous field initialization rather than lifecycle registration:
+
+```typescript
+import { zLoad, zOnConstructed, zOnLaunch, zOnStart } from '@zcomponent/core';
+
+@zOnConstructed()
+private _afterConstruction() {
+	// The full entity tree has been constructed
+}
+
+@zOnLaunch()
+private _afterLaunch() {
+	// The user has launched the experience
+}
+
+@zOnStart()
+private _afterStart() {
+	// Start audio, video, or animation
+}
+
+@zLoad()
+private async _load() {
+	// The loader waits for this promise before completing
+}
+```
+
+## Accessing ZComponent Nodes and Animation
+
+Access the ZComponent instance and its nodes:
+
+```typescript
+import Scene from './Scene.zcomp';
+
+const scene = this.getZComponentInstance(Scene);
+
+// Access nodes by scriptName
+scene.nodes.DirectionalLight.enabled = false;
+
+// Access animation layers and clips
+scene.animation.layers.MyLayer.clips.MyTimeline.play();
+scene.animation.layers.MyLayer.active = null; // Fade out
+```
+
+## File References
+
+Reference files using the URL constructor with import.meta.url:
+
+```typescript
+const fileUrl = new URL('./myfile.png', import.meta.url);
+```
+
+This format ensures Mattercraft's bundler detects and includes the file in the output bundle.