@holoscript/core 6.0.3 → 7.0.0

package/dist/index.d.ts

@@ -44,6 +44,27 @@ export class HoloScriptPlusParser {
   parseStatement(source: string): any;
 }
 
+export class HSPlusRuntime {
+  constructor(options?: any);
+  mount(container: any): void;
+  unmount(): void;
+  update(delta: number): void;
+  setState(updates: Record<string, any>): void;
+  getState(): Record<string, any>;
+  on(event: string, handler: (payload: any) => void): () => void;
+  emit(event: string, payload?: any): void;
+}
+
+export class World {
+  constructor();
+  createEntity(): string;
+  removeEntity(id: string): void;
+}
+
+export class ComponentRegistry {
+  static register(name: string, component: any): void;
+}
+
 export class HoloCompositionParser {
   parse(source: string): any;
 }
@@ -59,6 +80,8 @@ export function parse(source: string, options?: any): ParseResult;
 export function parseHolo(source: string, options?: any): any;
 export function parseHoloStrict(source: string): any;
 export function parseHoloScriptPlus(source: string, options?: any): ParseResult;
+export const holoFactory: any;
+export function generateHoloSource(ast: any): string;
 
 // ============================================================================
 // COMPOSITION TYPES (from .holo files)
@@ -114,6 +137,7 @@ export interface HoloObjectTrait extends ASTNode {
   type: 'Trait';
   name: string;
   config?: any;
+  args?: any[];
 }
 
 export interface HoloSpatialGroup extends ASTNode {
@@ -140,6 +164,10 @@ export interface HoloAction extends ASTNode {
   [key: string]: any;
 }
 
+export interface HoloStatement extends ASTNode {
+  [key: string]: any;
+}
+
 export interface HoloParseResult {
   success: boolean;
   ast?: HoloComposition;
@@ -414,12 +442,14 @@ export class AdvancedCompression {
 }
 
 export interface INeuralSplatPacket {
-  id: string;
-  frameId?: number;
-  count: number;
-  data: Uint8Array;
-  metadata?: Record<string, any>;
-  cameraState?: any;
+  frameId: number;
+  cameraState: {
+    viewProjectionMatrix: number[];
+    cameraPosition: number[];
+  };
+  splatCount: number;
+  compressedSplatsBuffer: ArrayBuffer;
+  sortedIndicesBuffer: ArrayBuffer;
 }
 
 // ============================================================================
@@ -534,8 +564,10 @@ export function compileForIsaacSim(composition: HoloComposition, options?: Parti
 // ============================================================================
 
 export class ExpressionEvaluator {
+  constructor(context?: Record<string, unknown>, builtins?: Record<string, unknown>);
   evaluate(expression: string, context?: any): any;
   extractVariables(expression: string): string[];
+  updateContext(updates: Record<string, unknown>): void;
 }
 
 export class EventBus {
@@ -648,9 +680,11 @@ export interface HoloTemplate {
   [key: string]: any;
 }
 export interface HSPlusForDirective {
-  iterable: string;
+  type: 'for';
   variable: string;
-  body?: any[];
+  range?: [number, number];
+  iterable?: string;
+  body: unknown[];
 }
 export interface RaycastHit {
   point: Vector3;
@@ -801,6 +835,11 @@ export interface SafetyReport {
 }
 
 export type SafetyVerdict = 'safe' | 'warnings' | 'unsafe' | 'unchecked';
+export type VREffect = string;
+export type EffectCategory = string;
+export type EffectViolationSeverity = 'error' | 'warning' | 'info';
+export interface EffectViolation { effect: VREffect; severity: EffectViolationSeverity; [key: string]: any; }
+export interface EffectDeclaration { effects: VREffect[]; [key: string]: any; }
 
 // ============================================================================
 // PLATFORM TYPES
@@ -869,18 +908,26 @@ export class SemanticSearchService<T = any> {
 // VR TRAIT SYSTEM TYPES
 // ============================================================================
 
-export interface Vector3 {
-  x: number;
-  y: number;
-  z: number;
-}
+// Vector3 is a tuple in source (packages/core/src/types/HoloScriptPlus.ts:10).
+// Emitting as {x,y,z} interface here in 2026-04-22..04-25 produced hundreds
+// of engine-package TS errors like "Type 'number[]' is missing properties
+// x,y,z from Vector3" because consumer code correctly uses tuple-form
+// (engine/src/animation/IKSolver.ts:139, etc). Restoring tuple form here
+// lets pre-flight pass; for {x,y,z} object shape use three.Vector3 directly.
+export type Vector3 = [number, number, number];
 
 export interface VRHand {
+  id: string;
   position: Vector3;
-  rotation: Vector3;
-  joints: Map<string, { position: Vector3; rotation: Vector3 }>;
-  pinchStrength: number;
-  gripStrength: number;
+  rotation: Quaternion;
+  velocity: Vector3;
+  joints?: Map<string, { position: Vector3; rotation: Vector3 }>;
+  pinch?: number;
+  pinchStrength?: number;
+  grip: number;
+  gripStrength?: number;
+  trigger: number;
+  pointing?: boolean;
 }
 
 export interface VRContext {
@@ -895,8 +942,8 @@ export interface PhysicsContext {
   applyAngularVelocity(node: HSPlusNode, angularVelocity: Vector3): void;
   setKinematic(node: HSPlusNode, kinematic: boolean): void;
   raycast(origin: Vector3, direction: Vector3, maxDistance: number): RaycastHit | null;
-  getBodyPosition(nodeId: string): { x: number; y: number; z: number } | null;
-  getBodyVelocity(nodeId: string): { x: number; y: number; z: number } | null;
+  getBodyPosition(nodeId: string): Vector3 | null;
+  getBodyVelocity(nodeId: string): Vector3 | null;
 }
 
 export interface AudioContext {
@@ -945,6 +992,24 @@ export interface HSPlusNode extends ASTNode {
   [key: string]: any;
 }
 
+export interface TraitBehavior {
+  readonly traitId: string;
+  readonly name: string;
+  enabled: boolean;
+  initialize?(): void | Promise<void>;
+  update?(deltaTime: number): void;
+  dispose?(): void | Promise<void>;
+}
+
+export class ProceduralSkill {
+  id: string;
+  name: string;
+  category: string;
+  description: string;
+  constructor(config: { id: string; name: string; category: string; description: string });
+  execute(input: unknown): unknown;
+}
+
 export type VRTraitName = string;
 
 export class VRTraitRegistry {
@@ -1597,6 +1662,7 @@ export type HoloScriptLogger = Logger;
 export function setHoloScriptLogger(logger: Logger): void;
 export function resetLogger(): void;
 export function enableConsoleLogging(): void;
+export const logger: HoloScriptLogger;
 export function isHoloScriptSupported(): boolean;
 
 // ============================================================================
@@ -2908,3 +2974,438 @@ export type HoloDomainType = string;
 export class TraitConstraint { [key: string]: any; }
 export interface ISignalingBridge { [key: string]: any; }
 export interface NeuralSignalPayload { [key: string]: any; }
+
+// ============================================================================
+// Visual logic graph (Studio bridge + PlayMode preview path)
+// ============================================================================
+export type PortType = 'number' | 'string' | 'boolean' | 'vec3' | 'any' | 'event';
+export interface PortDefinition {
+  name: string;
+  type: PortType;
+  defaultValue?: unknown;
+}
+export interface LogicNode {
+  id: string;
+  type: string;
+  inputs: PortDefinition[];
+  outputs: PortDefinition[];
+  position: { x: number; y: number };
+  data: Record<string, unknown>;
+}
+export interface LogicConnection {
+  id: string;
+  fromNode: string;
+  fromPort: string;
+  toNode: string;
+  toPort: string;
+}
+export interface EvaluationContext {
+  state: Record<string, unknown>;
+  deltaTime: number;
+  events: Map<string, unknown[]>;
+  emittedEvents: Map<string, unknown[]>;
+}
+export declare class NodeGraph {
+  readonly id: string;
+  constructor(id?: string);
+  addNode(
+    type: string,
+    position?: { x: number; y: number },
+    data?: Record<string, unknown>
+  ): LogicNode;
+  connect(
+    fromNode: string,
+    fromPort: string,
+    toNode: string,
+    toPort: string
+  ): LogicConnection | null;
+  getNode(nodeId: string): LogicNode | undefined;
+  getNodes(): LogicNode[];
+  getConnections(): LogicConnection[];
+  topologicalSort(): string[];
+  evaluate(context: EvaluationContext): Map<string, Record<string, unknown>>;
+}
+export interface NodeGraphExecutionResult {
+  nodeOrder: string[];
+  outputs: Map<string, Record<string, unknown>>;
+  state: Record<string, unknown>;
+  emittedEvents: Map<string, unknown[]>;
+}
+export interface NodeGraphPanelConfig {
+  position: [number, number, number];
+  nodeWidth: number;
+  nodeHeight: number;
+  gridSpacing: number;
+}
+export interface UIEntity {
+  id: string;
+  type: 'panel' | 'label' | 'port' | 'connection_line';
+  position: [number, number, number];
+  size?: { width: number; height: number };
+  text?: string;
+  color?: string;
+  data?: Record<string, unknown>;
+}
+export declare class NodeGraphPanel {
+  constructor(graph: NodeGraph, config?: Partial<NodeGraphPanelConfig>);
+  generateUI(): UIEntity[];
+  selectNode(nodeId: string | null): void;
+  getSelectedNode(): string | null;
+  executeGraph(contextOverrides?: Partial<EvaluationContext>): NodeGraphExecutionResult;
+}
+export declare function emitPreviewHoloScriptFromNodeGraphExecution(
+  execution: NodeGraphExecutionResult,
+  graph: NodeGraph
+): string;
+
+// ============================================================================
+// Agent Extension Types — mirrored from src/extensions/AgentExtensionTypes.ts.
+// Added 2026-04-25 to unblock packages/framework imports of these types.
+// Update both this block AND src/extensions/AgentExtensionTypes.ts if shape
+// changes; CLAUDE.md flags dist/index.d.ts as hand-crafted (not tsc).
+// ============================================================================
+
+export interface IHiveContribution {
+  id: string;
+  agentId: string;
+  timestamp: number;
+  type: 'idea' | 'critique' | 'consensus' | 'solution';
+  content: string;
+  confidence: number;
+}
+
+export interface IHiveSession {
+  id: string;
+  topic: string;
+  goal: string;
+  initiator: string;
+  status: 'active' | 'resolved' | 'closed';
+  participants: string[];
+  contributions: IHiveContribution[];
+  resolution?: unknown;
+}
+
+export interface ICollectiveIntelligenceService {
+  createSession(topic: string, goal: string, initiator: string): IHiveSession | Promise<string>;
+  join(sessionId: string, agentId: string): void | Promise<void>;
+  leave(sessionId: string, agentId: string): void | Promise<void>;
+  contribute(
+    sessionId: string,
+    contribution: Omit<IHiveContribution, 'id' | 'timestamp'>
+  ): IHiveContribution | Promise<void>;
+  vote(
+    sessionId: string,
+    contributionId: string,
+    voterId: string,
+    vote: 'support' | 'oppose'
+  ): void | Promise<void>;
+  synthesize(sessionId: string): unknown;
+  resolve(sessionId: string, resolution: string | unknown): void | Promise<void>;
+}
+
+export interface ISwarmConfig {
+  algorithm: 'pso' | 'aco' | 'bees' | 'hybrid';
+  populationSize: number;
+  maxIterations: number;
+  convergenceThreshold: number;
+  adaptiveSizing?: boolean;
+}
+
+export interface ISwarmResult {
+  bestSolution: number[];
+  bestFitness: number;
+  converged: boolean;
+  iterations: number;
+  improvementPercent: number;
+}
+
+export interface ISwarmCoordinator {
+  optimize(
+    agents: { id: string; capacity: number; load: number }[],
+    tasks: { id: string; complexity: number; priority: number }[],
+    config?: Partial<ISwarmConfig>
+  ): Promise<ISwarmResult>;
+  getRecommendedPopulation(problemSize: number): number;
+}
+
+export interface ILeaderElection {
+  startElection(): Promise<string>;
+  getLeader(): string | null;
+  getRole(): 'leader' | 'follower' | 'candidate';
+  onLeaderChange(callback: (leaderId: string | null) => void): () => void;
+}
+
+// ============================================================================
+// SUPPLEMENTAL EXPORTS — fills the gap between the runtime barrel
+// (`packages/core/src/barrel/index.ts` + `barrel/culture-agents.ts` +
+// `migration/SchemaDiff.ts` + `types/HoloScriptPlus.ts` + `traits/LipSyncTrait.ts`)
+// and the hand-crafted public d.ts. Engine + studio consumers import these from
+// `@holoscript/core`; without these declarations the imports fail strict tsc
+// (TS2614 / TS2724) even though the runtime symbols ARE present (re-exported
+// via barrels). See W.099 deploy-blocker sweep.
+// ============================================================================
+
+// ── HSPlus runtime / parser surface ─────────────────────────────────────────
+
+/** Runtime-injected helper functions exposed to user scripts. */
+export interface HSPlusBuiltins {
+  log: (...args: unknown[]) => void;
+  warn: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void;
+  setTimeout: (fn: () => void, ms: number) => number;
+  clearTimeout: (id: number) => void;
+  setInterval?: (fn: () => void, ms: number) => number;
+  clearInterval?: (id: number) => void;
+  fetch?: (url: string, options?: unknown) => Promise<unknown>;
+  emit?: (event: string, data?: unknown) => void;
+  on?: (event: string, handler: (data: unknown) => void) => void;
+  off?: (event: string, handler?: (data: unknown) => void) => void;
+  showSettings?: () => void;
+  openChat?: (config?: unknown) => void;
+  assistant_generate?: (prompt: string, context?: string) => void;
+  [key: string]: unknown;
+}
+
+/** Parser directive variants — discriminated by `type`. Mirrors
+ * `packages/core/src/types/AdvancedTypeSystem.ts:396`. Engine + studio
+ * consumers narrow via `directive.type === 'lifecycle'` etc. */
+
+export interface HSPlusBaseDirective {
+  type: 'directive' | 'fragment';
+  name: string;
+  args: string[];
+}
+
+export interface HSPlusTraitDirective {
+  type: 'trait';
+  name: string;
+  args?: unknown[];
+  config?: Record<string, unknown>;
+}
+
+export interface HSPlusLifecycleDirective {
+  type: 'lifecycle';
+  name?: string;
+  hook: string;
+  params?: string[];
+  body: string;
+}
+
+export interface HSPlusStateDirective {
+  type: 'state';
+  name?: string;
+  body?: Record<string, unknown>;
+  initial?: unknown;
+}
+
+export interface HSPlusForEachDirective {
+  type: 'forEach';
+  variable: string;
+  collection: string;
+  body: unknown[];
+}
+
+export interface HSPlusWhileDirective {
+  type: 'while';
+  condition: string;
+  body: unknown[];
+}
+
+export interface HSPlusIfDirective {
+  type: 'if';
+  condition: string;
+  body: unknown[];
+  else?: unknown[];
+}
+
+export interface HSPlusImportDirective {
+  type: 'import';
+  path: string;
+  alias: string;
+  namedImports?: string[];
+  isWildcard?: boolean;
+}
+
+export interface HSPlusVersionDirective {
+  type: 'version';
+  version: number;
+}
+
+export interface HSPlusMigrateDirective {
+  type: 'migrate';
+  fromVersion: number;
+  body: string;
+}
+
+export interface HSPlusBindingsDirective {
+  type: 'bindings';
+  bindings: unknown[];
+}
+
+export interface HSPlusExportDirective {
+  type: 'export';
+  exportKind: string;
+  exportName: string;
+}
+
+export interface HSPlusConfigDirective {
+  type:
+    | 'world_metadata'
+    | 'world_config'
+    | 'skybox'
+    | 'ambient_light'
+    | 'fog'
+    | 'artwork_metadata'
+    | 'npc_behavior';
+  [key: string]: unknown;
+}
+
+export interface HSPlusNamedConfigDirective {
+  type: 'manifest' | 'semantic' | 'directional_light';
+  name: string;
+  [key: string]: unknown;
+}
+
+/** Discriminated union of every parser directive. `HSPlusForDirective` is
+ * declared earlier in this d.ts; the rest live above. */
+export type HSPlusDirective =
+  | HSPlusBaseDirective
+  | HSPlusTraitDirective
+  | HSPlusLifecycleDirective
+  | HSPlusStateDirective
+  | HSPlusForDirective
+  | HSPlusForEachDirective
+  | HSPlusWhileDirective
+  | HSPlusIfDirective
+  | HSPlusImportDirective
+  | HSPlusVersionDirective
+  | HSPlusMigrateDirective
+  | HSPlusBindingsDirective
+  | HSPlusExportDirective
+  | HSPlusConfigDirective
+  | HSPlusNamedConfigDirective;
+
+// ── State migration (packages/core/src/migration/SchemaDiff.ts) ─────────────
+
+export type FieldChangeKind =
+  | 'added'
+  | 'removed'
+  | 'type-changed'
+  | 'default-changed'
+  | 'reactive-changed'
+  | 'unchanged';
+
+export interface FieldChange {
+  kind: FieldChangeKind;
+  key: string;
+  oldValue?: HoloValue;
+  newValue?: HoloValue;
+  oldType?: string;
+  newType?: string;
+  requiresMigration: boolean;
+}
+
+export interface SchemaDiffResult {
+  hasChanges: boolean;
+  changes: FieldChange[];
+  added: FieldChange[];
+  removed: FieldChange[];
+  typeChanged: FieldChange[];
+  defaultChanged: FieldChange[];
+  reactiveChanged: FieldChange[];
+  requiresMigration: boolean;
+  summary: string;
+}
+
+export interface MigrationStep {
+  fromVersion: number;
+  /** Statement list (parsed nodes) OR raw code string. */
+  body: unknown[] | string;
+}
+
+export interface MigrationChain {
+  fromVersion: number;
+  toVersion: number;
+  steps: MigrationStep[];
+}
+
+export function diffState(
+  oldState: HoloState | undefined,
+  newState: HoloState | undefined
+): SchemaDiffResult;
+export function buildMigrationChain(
+  template: HoloTemplate,
+  oldVersion: number,
+  newVersion: number
+): MigrationChain | null;
+export function snapshotState(state: Map<string, HoloValue>): Map<string, HoloValue>;
+export function applyAutoMigration(
+  instanceState: Map<string, HoloValue>,
+  diff: SchemaDiffResult,
+  oldDefaults: Map<string, HoloValue>
+): void;
+
+// ── State machine AST node (packages/core/src/types.ts:735) ─────────────────
+
+export interface StateMachineNode extends ASTNode {
+  type: 'state-machine';
+  name: string;
+  initialState: string;
+  states: any[];
+  transitions: any[];
+}
+
+// ── Lip-sync (packages/core/src/traits/LipSyncTrait.ts) ─────────────────────
+
+export interface PhonemeTimestamp {
+  phoneme: string;
+  time: number;
+  duration: number;
+  weight?: number;
+}
+
+// ── Culture / norms / WebRTC: NOT re-exported here.
+//    These types live in `@holoscript/framework/agents` and `@holoscript/mesh`.
+//    Engine consumers should import them DIRECTLY from those packages — both
+//    are explicit dependencies of `@holoscript/engine`. Earlier attempts to
+//    surface them through core's hand-crafted d.ts caused cascading TS2571
+//    "Object is of type 'unknown'" errors because the minimal shapes here
+//    couldn't keep up with the full method surface of `CulturalMemory` /
+//    `NormEngine` classes. See engine/src/runtime/CultureRuntime.ts +
+//    voice/VoiceManager.ts for the corrected import paths. ─────────────────
+
+// ── Quaternion (packages/core/src/types/HoloScriptPlus.ts:26) ───────────────
+
+export type Quaternion = [number, number, number, number];
+
+// ── WebRTC transport (re-exported from @holoscript/mesh via
+//    packages/core/src/barrel/registry-deploy-events.ts). Engine's
+//    audio/VoiceManager.ts pulls a small subset; we mirror just that
+//    surface here so the public d.ts isn't the wrong-shape lie that
+//    blocked deploy pre-flight (W.099). Full surface lives in mesh. ─────────
+
+export interface WebRTCTransportConfig {
+  signalingUrl?: string;
+  iceServers?: unknown[];
+  [key: string]: unknown;
+}
+
+export class WebRTCTransport {
+  constructor(config?: WebRTCTransportConfig);
+  connect(): Promise<void>;
+  disconnect(): void;
+  setMicrophoneEnabled(enabled: boolean): void;
+  on(event: string, handler: (...args: unknown[]) => void): void;
+  off(event: string, handler?: (...args: unknown[]) => void): void;
+}
+
+// ── Host capabilities (packages/core/src/traits/TraitTypes.ts:134) ──────────
+
+export interface HostCapabilities {
+  fileSystem?: unknown;
+  process?: unknown;
+  network?: unknown;
+  media?: unknown;
+  depthInference?: unknown;
+  gpuCompute?: unknown;
+}

package/dist/paper-0c-spike/index.d.ts

@@ -0,0 +1,29 @@
+/** @holoscript/core/paper-0c-spike — CAEL paper-0c primitives (subgrid attestation) */
+export type HashMode = 'fnv1a' | 'sha256';
+export declare const DEFAULT_HASH_MODE: HashMode;
+export type SubgridParamValue = number | boolean | string;
+export type SubgridParams = Record<string, SubgridParamValue>;
+export interface SubgridAttestation {
+  readonly hash: string;
+  readonly hashMode: HashMode;
+  readonly canonicalForm: string;
+}
+export type VerifyResult =
+  | { readonly valid: true }
+  | {
+      readonly valid: false;
+      readonly reason: 'hashMode-mismatch' | 'hash-mismatch' | 'canonical-form-mismatch';
+      readonly expected: string;
+      readonly actual: string;
+    };
+export declare class MissingSubgridParamsError extends Error { constructor(); }
+export declare class InvalidSubgridParamValueError extends Error { constructor(key: string, value: unknown); }
+export declare function canonicalizeSubgridParams(params: SubgridParams): string;
+export declare function hashSubgridParams(params: SubgridParams, mode: 'fnv1a'): string;
+export declare function hashSubgridParams(params: SubgridParams, mode: 'sha256'): Promise<string>;
+export declare function hashSubgridParams(params: SubgridParams, mode?: HashMode): string | Promise<string>;
+export declare function attestSubgridParams(params: SubgridParams, mode: 'fnv1a'): SubgridAttestation;
+export declare function attestSubgridParams(params: SubgridParams, mode: 'sha256'): Promise<SubgridAttestation>;
+export declare function attestSubgridParams(params: SubgridParams, mode?: HashMode): SubgridAttestation | Promise<SubgridAttestation>;
+export declare function verifySubgridAttestation(attestation: SubgridAttestation, params: SubgridParams): VerifyResult;
+export declare function verifySubgridAttestationAsync(attestation: SubgridAttestation, params: SubgridParams): Promise<VerifyResult>;