@energy8platform/golem 0.6.0 → 0.7.0

package/dist/lib/e8/agent.d.ts

@@ -0,0 +1,35 @@
+import type { AgentTool, AgentWriteFrame, E8Context } from "./types";
+/** String arguments naming a file or directory; `path` itself (rig.json) is resolved from the project root, these from the rig's directory. */
+export declare const PATH_ARGS: readonly ["library", "json", "atlas", "image", "layersDir", "relPrefix", "file", "outDir", "outFile", "output", "saveTo", "framesDir", "src"];
+/** String arguments that are not paths. A string argument in neither list fails tests/e8-agent.test.ts. */
+export declare const TEXT_ARGS: readonly ["animation", "asset", "attachment", "background", "bone", "clip", "color", "driver", "id", "name", "notes", "parent", "preset", "prompt", "prop", "rename", "role", "skin", "slot", "target", "to", "weightBone", "bind", "bones", "from", "frontOf", "groups", "order", "removed", "secondaryBones", "slots"];
+/** Nested arguments whose string values golem reads from disk at call time (resolved from the rig's directory); each value is checked and kept as written. */
+export declare const NESTED_PATH_ARGS: readonly ["debugFillMasks"];
+/** Strings nested inside other arguments that are not paths (or only land in rig.json as data); the test enumerates them. */
+export declare const NESTED_TEXT_ARGS: readonly ["a", "animation", "b", "bone", "control", "from", "id", "label", "name", "prompt", "prop", "requiredAnimations", "sourceImage", "src", "to", "v", "whenSlotVisible"];
+/**
+ * `args` with every path made absolute and checked to stay under `root`; throws naming the argument otherwise. Top-level PATH_ARGS are resolved from
+ * the rig's directory and checked (an empty one is left as given, STORED ones stay relative); an empty `path` is refused; NESTED_PATH_ARGS (debugFillMasks values) are checked against it and kept as written.
+ * NESTED_TEXT_ARGS (e.g. rig_set_meta's reference.src, which golem refuses when absolute or `..`) are data stored in rig.json;
+ * a rig.json whose asset srcs point out is refused by checkRigAssets.
+ * ponytail: a lexical check (path.resolve), no realpath — a symlink inside the project that points out passes;
+ * resolve the nearest existing ancestor with realpath if projects start carrying such links.
+ */
+export declare function sandboxArgs(root: string, args: Record<string, unknown>): Record<string, unknown>;
+/** Every registry tool as an e8 agent tool over the project at `root`; `announce` gets one frame per call that changed a rig (NO_STEP tools aside). */
+export declare function rigAgentTools(root: string, announce: (frame: AgentWriteFrame) => void): AgentTool<Record<string, unknown>>[];
+interface AgentHostContext extends E8Context {
+    project: {
+        root: string;
+    };
+    tools: {
+        register(tool: AgentTool, owner?: string): () => void;
+    };
+    ideRpc: {
+        broadcastAgentWrite(frame: AgentWriteFrame): void;
+    };
+}
+export declare const name = "golem-agent";
+export declare const inject: string[];
+export declare function apply(ctx: AgentHostContext): void;
+export {};

package/dist/lib/e8/host.d.ts

@@ -0,0 +1,22 @@
+/** e8/host — the host half of golem's e8 row (an `e8.yml` entry): the rig editor under /golem/ on the IDE's own port. */
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { E8Context } from "./types";
+/** The slice of @cordisjs/plugin-server's request and response this uses: the raw node objects underneath. */
+interface RawRequest {
+    _req: IncomingMessage;
+}
+interface RawResponse {
+    _res: ServerResponse;
+}
+interface HostContext extends E8Context {
+    project: {
+        root: string;
+    };
+    server: {
+        all(path: RegExp, handler: (req: RawRequest, res: RawResponse) => Promise<void>): unknown;
+    };
+}
+export declare const name = "golem-editor";
+export declare const inject: string[];
+export declare function apply(ctx: HostContext): void;
+export {};

package/dist/lib/e8/node.d.ts

@@ -0,0 +1,66 @@
+/**
+ * e8/node — the `golem` scene node type for e8-engine: a rig.json playing one animation, with expression controls.
+ * `rigLoader` (a pixi load parser) turns the loaded JSON into the document plus its textures, so the scenes runtime's
+ * loader hands this node a ready rig.
+ */
+import { ExtensionType, type Texture } from "pixi.js";
+import { type RigDocument } from "../rig-format";
+import type { NodeType } from "./types";
+export interface GolemProps {
+    rig: string;
+    animation?: string;
+    loop?: boolean;
+    speed?: number;
+    controls?: Record<string, number>;
+}
+/** What `rigLoader` leaves in the Assets cache for a rig.json: the document, its textures and the URLs they came from. */
+export interface LoadedRig {
+    doc: RigDocument;
+    textures: Map<string, Texture>;
+    sources: string[];
+}
+export interface TickerLike {
+    add(fn: (t: {
+        deltaMS: number;
+    }) => void): unknown;
+    remove(fn: (t: {
+        deltaMS: number;
+    }) => void): unknown;
+}
+export declare const isLoadedRig: (v: unknown) => v is LoadedRig;
+/** An asset `src` (relative to the rig file) as a URL the page loads; a root-relative rig URL gives a root-relative one. */
+export declare function resolveSrc(rigUrl: string, src: string): string;
+/**
+ * The pixi load parser: any loader may have read the JSON (pixi's own, Spine's), this one claims it by content.
+ * ponytail: textures load under rig-private URLs — two rigs sharing one PNG each load their own copy, and unloading
+ * one never touches an image node's; share per URL with a reference count if rigs start sharing many files.
+ */
+export declare function createRigLoader(io?: {
+    load(url: string): Promise<Texture>;
+    unload(urls: string[]): Promise<void>;
+}): {
+    extension: {
+        type: ExtensionType;
+        name: string;
+    };
+    name: string;
+    testParse(asset: unknown): Promise<boolean>;
+    parse(asset: unknown, resolved?: {
+        src?: string;
+    }): Promise<LoadedRig>;
+    unload(rig: unknown): Promise<void>;
+};
+export declare const rigLoader: {
+    extension: {
+        type: ExtensionType;
+        name: string;
+    };
+    name: string;
+    testParse(asset: unknown): Promise<boolean>;
+    parse(asset: unknown, resolved?: {
+        src?: string;
+    }): Promise<LoadedRig>;
+    unload(rig: unknown): Promise<void>;
+};
+export declare function createGolemNode(ticker: TickerLike): NodeType<GolemProps>;
+export declare const golemNode: NodeType<GolemProps>;

package/dist/lib/e8/runtime.d.ts

@@ -0,0 +1,10 @@
+import type { E8Context, NodeType } from "./types";
+export { golemNode, rigLoader, createGolemNode, createRigLoader, resolveSrc, isLoadedRig, type GolemProps, type LoadedRig } from "./node";
+interface RuntimeContext extends E8Context {
+    nodeTypes: {
+        register(type: NodeType<any>): () => void;
+    };
+}
+export declare const name = "golem";
+export declare const inject: string[];
+export declare function apply(ctx: RuntimeContext): void;

package/dist/lib/e8/schema.d.ts

@@ -0,0 +1,3 @@
+/** e8/schema — the form the e8 IDE draws for the golem row: nothing to configure; the node type carries its own props. */
+import Schema from "schemastery";
+export declare const Config: Schema<Schemastery.ObjectS<{}>, Schemastery.ObjectT<{}>>;

package/dist/lib/e8/types.d.ts

@@ -0,0 +1,80 @@
+/**
+ * e8/types — structural copies of the e8-engine shapes golem plugs into. `@energy8engine/*` are private packages, so
+ * golem cannot import them; e8-engine's typecheck holds these to the originals (its ide/host/tests/golem-contract.test.ts).
+ */
+import type { Container } from "pixi.js";
+import type Schema from "schemastery";
+declare global {
+    namespace Schemastery {
+        interface Meta<T> {
+            /** e8 IDE hint: this string field holds a project-relative asset path with one of these extensions */
+            asset?: string[];
+            /** e8 IDE hint: this string field names a document of this kind */
+            pick?: string;
+        }
+    }
+}
+/** The slice of a cordis context these plugins use. */
+export interface E8Context {
+    effect(execute: () => () => void, label?: string): void;
+}
+/** What a node type reads off the scenes runtime's context. */
+export interface NodeContext {
+    reflect: {
+        get(name: string, strict?: boolean): unknown;
+    };
+}
+export interface AssetLoader {
+    get(path: string): unknown;
+}
+export interface NodeType<P> {
+    type: string;
+    schema: Schema<P>;
+    mount(props: P, ctx: NodeContext): Container;
+    update?(view: Container, props: P, ctx: NodeContext): void;
+    once?(view: Container, props: P, ctx: NodeContext): Promise<void>;
+    unmount?(view: Container): void;
+    assets?(props: P): string[];
+    /** project files a filled-in view also reads besides `assets` (a rig's PNGs); a change to one reloads this node's assets */
+    dependsOn?(props: P, ctx: NodeContext): string[];
+    accept?: {
+        extensions: string[];
+        prop: string;
+        sibling?: string;
+    };
+    assetProps?: string[];
+}
+export type AgentContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+};
+export interface AgentToolContent {
+    kind: "agent-content";
+    content: AgentContent[];
+}
+export interface AgentInput<A> {
+    (value?: any): A;
+    toJSON(): unknown;
+    /** a ready JSON Schema for the arguments — e8 uses it as is instead of reading a schemastery graph */
+    jsonSchema?: Record<string, unknown>;
+}
+export interface AgentTool<A = any> {
+    name: string;
+    description: string;
+    input: AgentInput<A>;
+    readOnly?: boolean;
+    execute(args: A, call: {
+        signal: AbortSignal;
+    }): Promise<unknown>;
+}
+/** An accepted agent write — the e8 IDE records it as one undo step under `key`. */
+export interface AgentWriteFrame {
+    key: string;
+    label: string;
+    before: unknown;
+    after: unknown;
+}