@cimplify/sdk 0.108.0 → 0.110.2

package/dist/interactives-authoring.d.ts

@@ -0,0 +1,231 @@
+interface AuthoringTopic {
+    readonly id: string;
+    readonly title: string;
+    readonly summary: string;
+    readonly body: string;
+}
+declare const AUTHORING_RULES = "Cimplify Interactives authoring rules\n\nProject layout. An Interactive is a folder: interactive.toml (manifest), cimplify.lock (pinned SDK, ctx and library versions; never edit it), package.json, tsconfig.json, src/client.ts (client entry, default export async function main(ctx: Ctx): Promise<void>), optional src/room.ts (shared rules), src/worker.ts (jobs) and src/tick.ts (an authoritative real-time tick room, [entries] tick; read the tick-rooms topic), src/conformance.ts for games (default export a frame hook factory used by the publication gates), tests/ (vitest), assets/ (models, textures, sounds, data).\n\nManifest (interactive.toml). Tables: [interactive] name, description, category (\"games\" or \"everyday\"), id (assigned on first publish, never invent one); [profile] kind (\"native\" for GenUI trees, \"canvas\" for games and creative surfaces), game (\"game_api\" for the Cimplify game API, \"wasm\" or \"godot\" for engine profiles), engine_features (list from: particles, raw_compute, raw_render, text, pick, post_shaders, audio, physics, models, images, ai, ui); [entries] client, room, worker, conformance, channels; [capabilities] each ctx scope with the reason shown to the player (for example share = \"Share your score with friends\"); [[providers]] every external destination with id, destination, data_use, purpose; [economy] currencies, items, odds, offers, rules; [ai] payer, budgets, characters, prompts, schemas, actions, styles; [rating] violence, sexuality, language, fear (each \"none\", \"mild\", \"moderate\" or \"strong\") and simulated_gambling (bool); [delivery] min_device_tier (\"low\", \"mid\", \"high\"), download_size (the brotli-compressed bytes a device transfers for what the package itself owns; the engine and SDK runtimes are shared platform code a device downloads once, and no package is billed for them), [[delivery.groups]] name, before_play, assets globs; [[content]] Workshop items (item, version, group).\n\nProfiles. Native profile code emits GenUI trees through ctx.ui and has no DOM. Canvas profile code runs in an isolated iframe; games use the Cimplify game API (@cimplify/sdk/game and @cimplify/sdk/game/kit, with @cimplify/sdk/game/kit/canvas for runCanvasGame). A game_api game never imports three, phaser or @dimforge/rapier3d-compat directly and never imports engine backends; the platform picks the engine.\n\nAllowed imports. Only @cimplify/sdk/interactives, @cimplify/sdk/game, @cimplify/sdk/game/kit, @cimplify/sdk/game/kit/canvas, @cimplify/sdk/game/kit/engine, @cimplify/sdk/game/kit/slots (typed template slots and remix manifests), the kit template entries (@cimplify/sdk/game/kit/shootout, runner, five-a-side, ludo, word, tycoon, danfo, courier, worlds, frontier, genesis), and relative imports inside the project. Node built-ins, URLs and unlisted npm packages are refused.\n\nAdmission refuses: eval, new Function, string timers, dynamic import(), require, fetch or XMLHttpRequest or WebSocket (network goes through ctx and declared providers only), raw DOM outside the canvas surface in the native profile, hard-coded URLs, minified or obfuscated code, binaries and prebuilt wasm, catastrophic regular expressions, text that collects passwords, card numbers or other credentials, payment wording outside ctx.wallet and host checkout, and any ctx scope used without a [capabilities] entry. TypeScript is checked in strict mode; every error blocks the build.\n\nPerformance doctrine. Frame and fixed-step code allocates nothing: create typed arrays, Vec3 and Quat scratch objects, materials, geometries and batches once in enter() or constructors, then reuse them. No array literals, closures, string building or object spreads inside fixedUpdate or update. Keep simulation in fixedUpdate (deterministic, fixed step) and presentation in update. Use game.random (seeded) for gameplay randomness, never Math.random. Use the detSin, detCos, detLog and detExp helpers inside simulation that must replay bit for bit. For hundreds or thousands of similar entities use an entity table (game.table, see the entity-tables topic): bulk op first, kernel second, cols or each third, cursor forEach last (on iOS, per-row JS above a few thousand rows is not viable: use bulk ops or kernels).\n\nStyle. Write clear TypeScript without comments. Name constants instead of repeating numbers. Keep the game playable on touch (virtual controls or pointer) and keyboard.\n\nSize. A template-scale game is a few hundred lines. Before writing your own inventory, shop, quest tracker, enemy waves, score and timer HUD, NPC daily routine, collectibles, checkpoints, arena or playtest bot, read the blocks topic and use the kit building blocks; they are allocation free and deterministic already.";
+declare const AUTHORING_TOPICS: readonly AuthoringTopic[];
+
+declare function authoringTopic(id: string): AuthoringTopic | null;
+declare function authoringGuide(ids?: readonly string[]): string;
+
+interface FileLines {
+    readonly path: string;
+    readonly lines: number;
+}
+interface GameLines {
+    readonly total: number;
+    readonly files: readonly FileLines[];
+}
+interface SourceText {
+    readonly path: string;
+    readonly source: string;
+}
+interface LineSource {
+    list(): Promise<readonly string[]>;
+    read(path: string): Promise<string | null>;
+}
+declare const EMPTY_GAME_LINES: GameLines;
+declare function countSourceLines(source: string): number;
+declare function isGameSourcePath(path: string): boolean;
+declare function countGameLines(files: Iterable<SourceText>): GameLines;
+declare function measureGameLines(project: LineSource): Promise<GameLines>;
+declare const TEMPLATE_LINE_CEILINGS: Readonly<Record<string, number>>;
+
+interface AuthoringToolSpec {
+    readonly name: string;
+    readonly description: string;
+    readonly input_schema: Readonly<Record<string, unknown>>;
+}
+interface AuthoringToolCall {
+    readonly id: string;
+    readonly name: string;
+    readonly input: Readonly<Record<string, unknown>>;
+}
+type AuthoringStop = "done" | "tools" | "truncated" | "refused";
+interface AuthoringReply {
+    readonly text: string;
+    readonly calls: readonly AuthoringToolCall[];
+    readonly stop: AuthoringStop;
+    readonly echo: unknown;
+}
+interface AuthoringToolResult {
+    readonly id: string;
+    readonly content: string;
+    readonly error: boolean;
+}
+type AuthoringMessage = {
+    readonly role: "user";
+    readonly text: string;
+} | {
+    readonly role: "assistant";
+    readonly reply: AuthoringReply;
+} | {
+    readonly role: "tool_results";
+    readonly results: readonly AuthoringToolResult[];
+};
+interface AuthoringModelRequest {
+    readonly system: string;
+    readonly messages: readonly AuthoringMessage[];
+    readonly tools: readonly AuthoringToolSpec[];
+}
+interface AuthoringModel {
+    send(request: AuthoringModelRequest): Promise<AuthoringReply>;
+}
+interface AuthoringProject {
+    list(): Promise<readonly string[]>;
+    read(path: string): Promise<string | null>;
+    write(path: string, content: string): Promise<void>;
+    remove(path: string): Promise<boolean>;
+}
+interface AuthoringDiagnostic {
+    readonly severity: "error" | "warning";
+    readonly code: string;
+    readonly message: string;
+    readonly file: string | null;
+    readonly line: number | null;
+}
+type AuthoringCheck = () => Promise<readonly AuthoringDiagnostic[]>;
+interface AuthoringChange {
+    readonly path: string;
+    readonly kind: "write" | "delete";
+}
+type AuthoringEvent = {
+    readonly kind: "text";
+    readonly text: string;
+} | {
+    readonly kind: "tool";
+    readonly name: string;
+    readonly path: string | null;
+} | {
+    readonly kind: "check";
+    readonly errors: number;
+    readonly round: number;
+};
+interface AuthoringTurnOptions {
+    readonly model: AuthoringModel;
+    readonly project: AuthoringProject;
+    readonly check: AuthoringCheck;
+    readonly request: string;
+    readonly history?: readonly AuthoringMessage[];
+    readonly maxSteps?: number;
+    readonly repairRounds?: number;
+    readonly onEvent?: (event: AuthoringEvent) => void;
+}
+type AuthoringEnd = "done" | "steps" | "truncated" | "refused";
+interface AuthoringOutcome {
+    readonly changed: readonly AuthoringChange[];
+    readonly summary: string;
+    readonly diagnostics: readonly AuthoringDiagnostic[];
+    readonly repairs: number;
+    readonly end: AuthoringEnd;
+    readonly messages: readonly AuthoringMessage[];
+    readonly lines: GameLines;
+    readonly lineDelta: number;
+}
+declare const DEFAULT_MAX_STEPS = 40;
+declare const DEFAULT_REPAIR_ROUNDS = 3;
+declare const MAX_READ_BYTES = 200000;
+declare const MAX_WRITE_BYTES = 400000;
+declare const AUTHORING_TOOLS: readonly AuthoringToolSpec[];
+declare function authoringSystemPrompt(): string;
+declare function normalizeProjectPath(raw: string): string | null;
+declare function writablePath(raw: string): string | null;
+declare function readablePath(raw: string): string | null;
+declare function formatDiagnostics(diagnostics: readonly AuthoringDiagnostic[]): string;
+declare function runAuthoringTurn(options: AuthoringTurnOptions): Promise<AuthoringOutcome>;
+
+declare const ANTHROPIC_AUTHORING_MODEL = "claude-opus-5-5";
+type AuthoringEffort = "low" | "medium" | "high" | "xhigh" | "max";
+interface AnthropicAuthoringOptions {
+    readonly apiKey: string;
+    readonly model?: string;
+    readonly baseUrl?: string;
+    readonly maxTokens?: number;
+    readonly effort?: AuthoringEffort;
+    readonly fallbacks?: boolean;
+    readonly fetch?: typeof fetch;
+}
+interface ContentBlock {
+    readonly type: string;
+    readonly text?: string;
+    readonly id?: string;
+    readonly name?: string;
+    readonly input?: unknown;
+}
+interface MessageResponse {
+    readonly content?: readonly ContentBlock[];
+    readonly stop_reason?: string | null;
+}
+declare function parseAnthropicReply(body: MessageResponse): AuthoringReply;
+declare function anthropicAuthoringModel(options: AnthropicAuthoringOptions): AuthoringModel;
+
+type ThreePortStatus = "auto" | "assisted" | "manual";
+type ThreePortArea = "scene" | "object" | "geometry" | "material" | "light" | "camera" | "renderer" | "loader" | "animation" | "controls" | "loop" | "input" | "math" | "dom" | "audio" | "picking";
+interface ThreePortMapping {
+    readonly three: string;
+    readonly area: ThreePortArea;
+    readonly status: ThreePortStatus;
+    readonly sdk: string;
+    readonly note: string;
+}
+interface ThreeGeometryRule {
+    readonly fn: string;
+    readonly defaults: readonly number[];
+    readonly simpleArgs: number;
+    readonly extendedFn: string | null;
+}
+type ThreeMaterialKind = "standard" | "physical" | "unlit" | "toon" | "matcap";
+interface ThreeMaterialRule {
+    readonly kind: ThreeMaterialKind;
+    readonly shininessToRoughness: boolean;
+    readonly roughness: number | null;
+}
+type ThreeLightKind = "directional" | "point" | "spot" | "ambient" | "hemisphere" | "rectArea";
+interface ThreeLightRule {
+    readonly light: ThreeLightKind;
+    readonly params: readonly string[];
+}
+declare const THREE_GEOMETRIES: Readonly<Record<string, ThreeGeometryRule>>;
+declare const THREE_MATERIALS: Readonly<Record<string, ThreeMaterialRule>>;
+declare const THREE_LIGHTS: Readonly<Record<string, ThreeLightRule>>;
+declare const THREE_MATERIAL_PROPERTIES: readonly string[];
+declare const THREE_TEXTURE_SLOTS: readonly string[];
+declare const THREE_SIDES: Readonly<Record<string, string>>;
+declare const THREE_CONTROLS: Readonly<Record<string, string>>;
+declare const THREE_MATH_HELPERS: Readonly<Record<string, string>>;
+declare const THREE_VECTOR_METHODS: Readonly<Record<string, string>>;
+declare const THREEJS_PORT_MAP: readonly ThreePortMapping[];
+type ThreePortResidueKind = "unconverted" | "advisory";
+interface ThreePortResidue {
+    readonly id: string;
+    readonly kind: ThreePortResidueKind;
+    readonly area: ThreePortArea;
+    readonly construct: string;
+    readonly file: string;
+    readonly line: number;
+    readonly column: number;
+    readonly source: string;
+    readonly hint: string;
+}
+interface ThreePortFileLines {
+    readonly path: string;
+    readonly lines: number;
+}
+interface ThreePortReport {
+    readonly source: readonly ThreePortFileLines[];
+    readonly output: readonly ThreePortFileLines[];
+    readonly linesBefore: number;
+    readonly linesAfter: number;
+    readonly gameLinesAfter: number;
+    readonly converted: number;
+    readonly convertedByArea: Readonly<Partial<Record<ThreePortArea, number>>>;
+    readonly residue: readonly ThreePortResidue[];
+}
+declare const THREEJS_PORT_TOPIC_ID = "porting-threejs";
+declare function threejsPortGuide(): string;
+declare const THREEJS_PORT_TOPIC: AuthoringTopic;
+declare function threejsPortRequest(report: ThreePortReport): string;
+
+export { ANTHROPIC_AUTHORING_MODEL, AUTHORING_RULES, AUTHORING_TOOLS, AUTHORING_TOPICS, type AnthropicAuthoringOptions, type AuthoringChange, type AuthoringCheck, type AuthoringDiagnostic, type AuthoringEffort, type AuthoringEnd, type AuthoringEvent, type AuthoringMessage, type AuthoringModel, type AuthoringModelRequest, type AuthoringOutcome, type AuthoringProject, type AuthoringReply, type AuthoringStop, type AuthoringToolCall, type AuthoringToolResult, type AuthoringToolSpec, type AuthoringTopic, type AuthoringTurnOptions, DEFAULT_MAX_STEPS, DEFAULT_REPAIR_ROUNDS, EMPTY_GAME_LINES, type FileLines, type GameLines, type LineSource, MAX_READ_BYTES, MAX_WRITE_BYTES, type SourceText, TEMPLATE_LINE_CEILINGS, THREEJS_PORT_MAP, THREEJS_PORT_TOPIC, THREEJS_PORT_TOPIC_ID, THREE_CONTROLS, THREE_GEOMETRIES, THREE_LIGHTS, THREE_MATERIALS, THREE_MATERIAL_PROPERTIES, THREE_MATH_HELPERS, THREE_SIDES, THREE_TEXTURE_SLOTS, THREE_VECTOR_METHODS, type ThreeGeometryRule, type ThreeLightKind, type ThreeLightRule, type ThreeMaterialKind, type ThreeMaterialRule, type ThreePortArea, type ThreePortFileLines, type ThreePortMapping, type ThreePortReport, type ThreePortResidue, type ThreePortResidueKind, type ThreePortStatus, anthropicAuthoringModel, authoringGuide, authoringSystemPrompt, authoringTopic, countGameLines, countSourceLines, formatDiagnostics, isGameSourcePath, measureGameLines, normalizeProjectPath, parseAnthropicReply, readablePath, runAuthoringTurn, threejsPortGuide, threejsPortRequest, writablePath };