@loom-dev/luau 0.0.0-stage → 0.14.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 astra-void
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/entry.d.ts

@@ -0,0 +1 @@
+export {}

package/dist/entry.js

@@ -0,0 +1,14 @@
+import { r as runLuauProject } from "./mount-2LXSpSYv.js";
+import { project } from "virtual:loom-luau-project";
+//#region src/entry.ts
+/**
+* `@loom-dev/luau/entry` — the client entry `@loom-dev/preview` gives a Luau
+* project's page: build the Rojo project the preview plugin serves, and start
+* the client. A real module rather than a generated one, so Vite's dependency
+* scan can follow it like any app entry.
+*/
+runLuauProject(project);
+//#endregion
+export {};
+
+//# sourceMappingURL=entry.js.map

package/dist/entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.js","names":[],"sources":["../src/entry.ts"],"sourcesContent":["/**\n * `@loom-dev/luau/entry` — the client entry `@loom-dev/preview` gives a Luau\n * project's page: build the Rojo project the preview plugin serves, and start\n * the client. A real module rather than a generated one, so Vite's dependency\n * scan can follow it like any app entry.\n */\nimport { project } from \"virtual:loom-luau-project\";\nimport { runLuauProject } from \"./mount.ts\";\n\nvoid runLuauProject(project);\n"],"mappings":";;;;;;;;;AASK,eAAe,OAAO"}

package/dist/index.d.ts

@@ -0,0 +1,352 @@
+import { LoomInstance } from "@loom-dev/runtime";
+import { World, WorldOptions } from "@loom-dev/react";
+import { FunctionComponent } from "react";
+//#region src/vm.d.ts
+/** An error raised in Luau, or by a host function on Luau's behalf. */
+declare class LuauError extends Error {
+  /** The raised value itself (`error({ code = 1 })` keeps its table). */
+  readonly value: unknown;
+  /** The Luau stack at the point of the error, when known. */
+  readonly traceback?: string | undefined;
+  readonly name = "LuauError";
+  constructor(message: string,
+  /** The raised value itself (`error({ code = 1 })` keeps its table). */
+  value?: unknown,
+  /** The Luau stack at the point of the error, when known. */
+  traceback?: string | undefined);
+}
+/** Several return values from a host function. */
+declare class Tuple {
+  readonly values: readonly unknown[];
+  constructor(values: readonly unknown[]);
+}
+/** Return several values from a host function. */
+declare function tuple(...values: unknown[]): Tuple;
+/**
+ * Returned by a host function to yield the thread that called it. `wait` runs
+ * once the thread has actually suspended and receives the function that
+ * resumes it with the host function's results.
+ */
+declare class Suspend {
+  readonly wait: (resume: (...values: unknown[]) => void) => void;
+  constructor(wait: (resume: (...values: unknown[]) => void) => void);
+}
+/**
+ * How Luau sees one kind of host object. Every hook is optional: a missing
+ * `index` makes every field read an error, a missing `namecall` every method
+ * call. Arithmetic hooks receive both operands, either of which may be the
+ * host object.
+ */
+interface HostClass<T extends object = object> {
+  /** What `typeof` returns. */
+  readonly name: string;
+  index?(self: T, key: unknown): unknown;
+  newindex?(self: T, key: unknown, value: unknown): void;
+  namecall?(self: T, method: string, args: unknown[]): unknown;
+  call?(self: T, args: unknown[]): unknown;
+  tostring?(self: T): string;
+  eq?(a: T, b: unknown): boolean;
+  lt?(a: unknown, b: unknown): boolean;
+  le?(a: unknown, b: unknown): boolean;
+  len?(self: T): number;
+  unm?(self: T): unknown;
+  add?(a: unknown, b: unknown): unknown;
+  sub?(a: unknown, b: unknown): unknown;
+  mul?(a: unknown, b: unknown): unknown;
+  div?(a: unknown, b: unknown): unknown;
+  idiv?(a: unknown, b: unknown): unknown;
+  mod?(a: unknown, b: unknown): unknown;
+  pow?(a: unknown, b: unknown): unknown;
+}
+/** Picks the `HostClass` for a JS object, or `undefined` to copy it as a table. */
+type Classifier = (value: object) => HostClass | undefined;
+interface LuauVMOptions {
+  /** Decides which JS objects cross as host userdata. */
+  classify?: Classifier;
+  /** Where an error that escapes a thread goes. Defaults to `console.error`. */
+  onError?: (error: LuauError) => void;
+  /** Wall-clock milliseconds one entry into Luau may run. 0 disables. */
+  budgetMs?: number;
+  /** Passed to emscripten — for loading the `.wasm` from somewhere unusual. */
+  locateFile?: (path: string, prefix: string) => string;
+  /** The `.wasm` bytes themselves, skipping the fetch (tests, Node). */
+  wasmBinary?: ArrayBuffer | Uint8Array;
+  /**
+   * Globals that stay writable tables after the freeze, one table each that
+   * every script shares — Roblox's `_G` and `shared`. The sandbox freezes
+   * every table it finds, so these are made fresh once it has run.
+   */
+  sharedTables?: readonly string[];
+}
+/** How a resumed thread came back. */
+type ThreadResult = {
+  readonly status: "done";
+  readonly values: unknown[];
+} | {
+  readonly status: "yielded";
+} | {
+  readonly status: "error";
+  readonly error: LuauError;
+};
+/** A reference that keeps a Luau value alive until the JS side is collected. */
+declare abstract class LuauRef {
+  /** @internal */ readonly vm: LuauVM;
+  /** @internal */ readonly ref: number;
+  constructor( /** @internal */ vm: LuauVM, /** @internal */ ref: number);
+}
+/** A Luau function. `call` runs it to completion; `spawn` gives it a thread. */
+declare class LuauFunction extends LuauRef {
+  call(...args: unknown[]): unknown[];
+  spawn(...args: unknown[]): ThreadResult;
+}
+/** A Luau table, read and written raw (no metamethods). */
+declare class LuauTable extends LuauRef {
+  get(key: unknown): unknown;
+  set(key: unknown, value: unknown): void;
+  /** `#t`. */
+  get length(): number;
+  /** Every key/value pair, in `next` order. */
+  entries(): [unknown, unknown][];
+  /** `t[1]` … `t[#t]`. */
+  array(): unknown[];
+}
+/** A Luau coroutine. */
+declare class LuauThread extends LuauRef {}
+/** A Luau value JS has no use for beyond handing it back (vector, buffer, …). */
+declare class LuauOpaque extends LuauRef {
+  readonly typeName: string;
+  constructor(vm: LuauVM, ref: number, typeName: string);
+}
+declare class LuauVM {
+  /** Instantiate the WASM module and open a fresh Luau state. */
+  static create(options?: LuauVMOptions): Promise<LuauVM>;
+  private readonly M;
+  private readonly L;
+  private readonly classify;
+  private readonly onError;
+  private readonly budgetMs;
+  private readonly sharedTables;
+  private readonly entries;
+  private readonly functionIds;
+  private readonly debugNames;
+  private readonly handles;
+  private readonly handleOf;
+  private nextHandle;
+  private readonly metatables;
+  private readonly metamethodIds;
+  private readonly refs;
+  private scratch;
+  private scratchSize;
+  private readonly lenPtr;
+  private depth;
+  private frozen;
+  private closed;
+  /** `run`'s `onFinish` for each thread still on its way to the end. */
+  private readonly finishers;
+  private constructor();
+  /** Define a global. Only before the first script runs (globals freeze then). */
+  setGlobal(name: string, value: unknown): void;
+  getGlobal(name: string): unknown;
+  /**
+   * Freeze the globals and the standard libraries, Roblox style. Runs on its
+   * own before the first script; scripts then see the frozen set through
+   * their own writable environment.
+   */
+  freeze(): void;
+  /** Compile `source` into a function, or throw the syntax error. */
+  load(source: string, chunkname?: string): LuauFunction;
+  /**
+   * Run `source` as a script: its own thread with its own global environment
+   * (the frozen globals plus `globals`), the way Roblox runs a Script or
+   * LocalScript. Returns how the thread first came back; `onFinish` hears how
+   * it ended, after however many yields (`require` of a module that yields).
+   */
+  run(source: string, options?: {
+    chunkname?: string;
+    globals?: Record<string, unknown>;
+    onFinish?: (result: ThreadResult) => void;
+  }): ThreadResult;
+  /**
+   * Call a Luau function to completion and return its results. A function
+   * that yields throws here — give it a thread with `spawn` instead.
+   */
+  call(fn: LuauFunction, args?: readonly unknown[]): unknown[];
+  /** Run a Luau function in a new thread (`task.spawn`). */
+  spawn(fn: LuauFunction, args?: readonly unknown[]): ThreadResult;
+  /**
+   * Resume a Luau thread (`task.defer`'s and `task.delay`'s, made with
+   * `coroutine.create`). A thread that cannot be resumed — finished, running,
+   * or closed by `task.cancel` — is left alone and gives `undefined`.
+   */
+  resumeThread(thread: LuauThread, args?: readonly unknown[]): ThreadResult | undefined;
+  /** Hand an error to `onError`, as if it had escaped a thread. */
+  report(error: LuauError): void;
+  /** Collect garbage now (tests use it to observe userdata release). */
+  collect(): void;
+  /** Close the state. Every reference into it is dead afterwards. */
+  close(): void;
+  /** Whether `close` has run: every entry into Luau throws afterwards. */
+  get isClosed(): boolean;
+  /** How many JS objects Luau currently holds as userdata. */
+  get liveHostObjects(): number;
+  /** @internal */
+  track(owner: LuauRef, ref: number): void;
+  /** @internal */
+  tableGet(table: LuauTable, key: unknown): unknown;
+  /** @internal */
+  tableSet(table: LuauTable, key: unknown, value: unknown): void;
+  /** @internal */
+  tableLength(table: LuauTable): number;
+  /** @internal */
+  tableEntries(table: LuauTable): [unknown, unknown][];
+  /** Resume `co` with the top `nargs` values of its stack. */
+  private resume;
+  private resumeOnce;
+  /**
+   * A host function returned `suspend` on thread `co`. Keep the thread alive
+   * and hand `wait` its resume function once Luau has unwound — only then is
+   * the thread really suspended, whoever resumed it.
+   */
+  /** The `lua_State*` behind a thread reference. */
+  private threadOf;
+  private suspend;
+  /** Run `fn` as one entry into Luau, under the run-time budget. */
+  private enter;
+  private register;
+  private hostCall;
+  private pushResults;
+  private hostRelease;
+  /** The host function behind metamethod `name`, shared by every class. */
+  private metamethod;
+  private classOf;
+  private metatableFor;
+  private read;
+  private readRange;
+  private push;
+  private pushHost;
+  private functionId;
+  private ensureStack;
+  private loadOnto;
+  private pushString;
+  /** A NUL-terminated copy of `value` in the scratch buffer (overwritten by the next use). */
+  private cstr;
+  /** A permanent NUL-terminated string: Luau keeps C function debug names by pointer. */
+  private debugName;
+  private reserve;
+}
+//#endregion
+//#region src/bindings.d.ts
+/**
+ * The Roblox class surface, bound to one VM. `classify` is what the VM is
+ * created with; `install` defines the globals once the VM exists.
+ */
+interface RobloxBindings {
+  readonly classify: Classifier;
+  install(vm: LuauVM): void;
+}
+declare function createRobloxBindings(): RobloxBindings;
+//#endregion
+//#region src/project.d.ts
+/** One instance of a project tree, as the preview plugin emits it. */
+interface LuauProjectNode {
+  readonly name: string;
+  readonly className: string;
+  /** A script's source. */
+  readonly source?: string;
+  readonly children?: readonly LuauProjectNode[];
+}
+interface LuauProject {
+  /** The `DataModel` root; its children are services. */
+  readonly tree: LuauProjectNode;
+}
+/** Attach `source` to a script instance (what `require` and `startClient` run). */
+declare function setScriptSource(script: LoomInstance, source: string): void;
+/** The source behind a script instance, if loom has one for it. */
+declare function getScriptSource(script: LoomInstance): string | undefined;
+/**
+ * `Clone`, keeping every script's source. The runtime copies instances but
+ * knows nothing about loom's source registry, so the two trees are walked side
+ * by side — `Clone` keeps child order and drops the non-Archivable ones.
+ */
+declare function cloneWithSources(original: LoomInstance): LoomInstance | undefined;
+/**
+ * Build `project` into the runtime's `game`, once per project object. A node
+ * whose name and class match an instance that already exists (a service,
+ * `StarterPlayerScripts`) is merged into it rather than duplicated.
+ */
+declare function instantiateProject(project: LuauProject): void;
+//#endregion
+//#region src/mount.d.ts
+/** How a Roblox-flavoured Luau VM is made: shared by every entry point. */
+interface LuauVMSetup {
+  /** Where an error that escapes a script thread goes. Defaults to `console.error`. */
+  onError?: (error: LuauError) => void;
+  /** Wall-clock milliseconds one entry into Luau may run. Defaults to 5000. */
+  budgetMs?: number;
+  /** The Luau VM's `.wasm` bytes, skipping the fetch (tests). */
+  wasmBinary?: ArrayBuffer | Uint8Array;
+}
+interface MountLuauOptions extends LuauVMSetup, WorldOptions {
+  /** The element to paint into; defaults to a fresh container under `#loom-root`. */
+  target?: HTMLElement;
+  /** The script's `Name`, which is also its chunk name in errors. */
+  name?: string;
+}
+/** A fresh VM with Roblox's globals installed, ready to run scripts. */
+declare function createLuauVM(setup?: LuauVMSetup): Promise<LuauVM>;
+interface LuauMount {
+  readonly vm: LuauVM;
+  readonly world: World;
+  /** The `LocalScript` the source runs as (`script` inside it). */
+  readonly script: LoomInstance;
+  /** How the script's thread first came back. */
+  readonly result: ThreadResult;
+  unmount(): void;
+}
+/**
+ * Run `source` as a LocalScript in a fresh VM and paint what it builds. The
+ * script sits inside the world's default ScreenGui, so the common
+ * `script.Parent` idiom lands its UI on screen, and anything it parents to
+ * `Players.LocalPlayer.PlayerGui` renders as its own layer.
+ */
+declare function mountLuau(source: string, options?: MountLuauOptions): Promise<LuauMount>;
+interface RunLuauProjectOptions extends LuauVMSetup, WorldOptions {
+  /** The element to paint into; defaults to a fresh container under `#loom-root`. */
+  target?: HTMLElement;
+}
+interface LuauProjectMount {
+  readonly vm: LuauVM;
+  readonly world: World;
+  /** Every LocalScript the client started, with how its thread first came back. */
+  readonly scripts: ReadonlyArray<{
+    readonly script: LoomInstance;
+    readonly result: ThreadResult;
+  }>;
+  unmount(): void;
+}
+/**
+ * Start a Rojo project the way a client joins a place: build the tree into
+ * `game`, then run every LocalScript a client runs (ReplicatedFirst, the
+ * StarterGui copy in PlayerGui, the StarterPlayerScripts copy in
+ * PlayerScripts) in one VM, so `require` shares each module between them.
+ */
+declare function runLuauProject(project: LuauProject, options?: RunLuauProjectOptions): Promise<LuauProjectMount>;
+//#endregion
+//#region src/preview.d.ts
+interface LuauPreviewOptions extends LuauVMSetup {
+  /** The script's `Name`, and its chunk name in errors. */
+  readonly name: string;
+  /** The gallery sidebar label; the file name when omitted. */
+  readonly title?: string;
+  /** The project around the target, so its `require`s find their modules. */
+  readonly project?: LuauProject;
+}
+interface LuauPreview {
+  readonly title: string;
+  readonly render: FunctionComponent;
+}
+/** The `preview` export a `*.loom.luau` file compiles to. */
+declare function luauPreview(source: string, options: LuauPreviewOptions): LuauPreview;
+//#endregion
+export { type Classifier, type HostClass, LuauError, LuauFunction, type LuauMount, LuauOpaque, type LuauPreview, type LuauPreviewOptions, type LuauProject, type LuauProjectMount, type LuauProjectNode, LuauTable, LuauThread, LuauVM, type LuauVMOptions, type LuauVMSetup, type MountLuauOptions, type RobloxBindings, type RunLuauProjectOptions, Suspend, type ThreadResult, Tuple, cloneWithSources, createLuauVM, createRobloxBindings, getScriptSource, instantiateProject, luauPreview, mountLuau, runLuauProject, setScriptSource, tuple };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/vm.ts","../src/bindings.ts","../src/project.ts","../src/mount.ts","../src/preview.ts"],"mappings":"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"}

package/dist/index.js

@@ -0,0 +1,65 @@
+import { _ as setScriptSource, a as LuauError, c as LuauTable, d as Suspend, f as Tuple, g as instantiateProject, h as getScriptSource, i as createRobloxBindings, l as LuauThread, m as cloneWithSources, n as mountLuau, o as LuauFunction, p as tuple, r as runLuauProject, s as LuauOpaque, t as createLuauVM, u as LuauVM } from "./mount-2LXSpSYv.js";
+import { createInstance, game } from "@loom-dev/runtime";
+import { createElement, useEffect, useState } from "react";
+//#region src/preview.ts
+/**
+* `preview.ts` — a `*.loom.luau` file as a gallery target.
+*
+* The gallery shell mounts `preview.render` as a React component, so a Luau
+* target is one: it renders a ScreenGui and, once React has made it, runs the
+* target's source as a LocalScript inside it. The script shares the shell's
+* world — what it parents under `script.Parent` paints beside React's own
+* instances — and an error that stops its first run reaches the shell's error
+* boundary the way a throwing component's would.
+*/
+function playerGui() {
+	return game.GetService("Players").LocalPlayer.WaitForChild("PlayerGui");
+}
+/** The `preview` export a `*.loom.luau` file compiles to. */
+function luauPreview(source, options) {
+	function LuauTarget() {
+		const [gui, setGui] = useState(null);
+		const [failure, setFailure] = useState();
+		if (failure) throw failure;
+		useEffect(() => {
+			if (gui === null) return;
+			let vm;
+			let cancelled = false;
+			const before = new Set(playerGui().GetChildren());
+			createLuauVM(options).then((created) => {
+				if (cancelled) {
+					created.close();
+					return;
+				}
+				vm = created;
+				if (options.project) instantiateProject(options.project);
+				const script = createInstance("LocalScript", options.name);
+				script.Parent = gui;
+				const result = created.run(source, {
+					chunkname: `=${options.name}`,
+					globals: { script }
+				});
+				if (result.status === "error") setFailure(result.error);
+			}, setFailure);
+			return () => {
+				cancelled = true;
+				vm?.close();
+				for (const child of playerGui().GetChildren()) if (!before.has(child)) child.Destroy();
+			};
+		}, [gui]);
+		return createElement("screengui", {
+			ref: setGui,
+			Name: options.name,
+			ResetOnSpawn: false
+		});
+	}
+	LuauTarget.displayName = `LuauTarget(${options.name})`;
+	return {
+		title: options.title ?? options.name,
+		render: LuauTarget
+	};
+}
+//#endregion
+export { LuauError, LuauFunction, LuauOpaque, LuauTable, LuauThread, LuauVM, Suspend, Tuple, cloneWithSources, createLuauVM, createRobloxBindings, getScriptSource, instantiateProject, luauPreview, mountLuau, runLuauProject, setScriptSource, tuple };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/preview.ts"],"sourcesContent":["/**\n * `preview.ts` — a `*.loom.luau` file as a gallery target.\n *\n * The gallery shell mounts `preview.render` as a React component, so a Luau\n * target is one: it renders a ScreenGui and, once React has made it, runs the\n * target's source as a LocalScript inside it. The script shares the shell's\n * world — what it parents under `script.Parent` paints beside React's own\n * instances — and an error that stops its first run reaches the shell's error\n * boundary the way a throwing component's would.\n */\nimport { createInstance, game, type LoomInstance } from \"@loom-dev/runtime\";\nimport {\n\tcreateElement,\n\ttype FunctionComponent,\n\tuseEffect,\n\tuseState,\n} from \"react\";\nimport { createLuauVM, type LuauVMSetup } from \"./mount.ts\";\nimport { instantiateProject, type LuauProject } from \"./project.ts\";\nimport type { LuauError, LuauVM } from \"./vm.ts\";\n\nexport interface LuauPreviewOptions extends LuauVMSetup {\n\t/** The script's `Name`, and its chunk name in errors. */\n\treadonly name: string;\n\t/** The gallery sidebar label; the file name when omitted. */\n\treadonly title?: string;\n\t/** The project around the target, so its `require`s find their modules. */\n\treadonly project?: LuauProject;\n}\n\nexport interface LuauPreview {\n\treadonly title: string;\n\treadonly render: FunctionComponent;\n}\n\nfunction playerGui(): LoomInstance {\n\tconst player = game.GetService(\"Players\").LocalPlayer as LoomInstance;\n\treturn player.WaitForChild(\"PlayerGui\") as LoomInstance;\n}\n\n/** The `preview` export a `*.loom.luau` file compiles to. */\nexport function luauPreview(\n\tsource: string,\n\toptions: LuauPreviewOptions,\n): LuauPreview {\n\tfunction LuauTarget() {\n\t\tconst [gui, setGui] = useState<LoomInstance | null>(null);\n\t\tconst [failure, setFailure] = useState<LuauError>();\n\t\tif (failure) throw failure;\n\n\t\tuseEffect(() => {\n\t\t\tif (gui === null) return;\n\t\t\tlet vm: LuauVM | undefined;\n\t\t\tlet cancelled = false;\n\t\t\t// A target may parent a ScreenGui straight to PlayerGui; that one is\n\t\t\t// not under React, so unmounting has to take it away by hand.\n\t\t\tconst before = new Set(playerGui().GetChildren());\n\t\t\tvoid createLuauVM(options).then((created) => {\n\t\t\t\tif (cancelled) {\n\t\t\t\t\tcreated.close();\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tvm = created;\n\t\t\t\tif (options.project) instantiateProject(options.project);\n\t\t\t\tconst script = createInstance(\"LocalScript\", options.name);\n\t\t\t\tscript.Parent = gui;\n\t\t\t\tconst result = created.run(source, {\n\t\t\t\t\tchunkname: `=${options.name}`,\n\t\t\t\t\tglobals: { script },\n\t\t\t\t});\n\t\t\t\tif (result.status === \"error\") setFailure(result.error);\n\t\t\t}, setFailure);\n\t\t\treturn () => {\n\t\t\t\tcancelled = true;\n\t\t\t\tvm?.close();\n\t\t\t\tfor (const child of playerGui().GetChildren()) {\n\t\t\t\t\tif (!before.has(child)) child.Destroy();\n\t\t\t\t}\n\t\t\t};\n\t\t}, [gui]);\n\n\t\treturn createElement(\"screengui\", {\n\t\t\tref: setGui,\n\t\t\tName: options.name,\n\t\t\tResetOnSpawn: false,\n\t\t});\n\t}\n\tLuauTarget.displayName = `LuauTarget(${options.name})`;\n\treturn { title: options.title ?? options.name, render: LuauTarget };\n}\n"],"mappings":";;;;;;;;;;;;;;AAmCA,SAAS,YAA0B;CAElC,OADe,KAAK,WAAW,SAAS,CAAC,CAAC,YAC5B,aAAa,WAAW;AACvC;;AAGA,SAAgB,YACf,QACA,SACc;CACd,SAAS,aAAa;EACrB,MAAM,CAAC,KAAK,UAAU,SAA8B,IAAI;EACxD,MAAM,CAAC,SAAS,cAAc,SAAoB;EAClD,IAAI,SAAS,MAAM;EAEnB,gBAAgB;GACf,IAAI,QAAQ,MAAM;GAClB,IAAI;GACJ,IAAI,YAAY;GAGhB,MAAM,SAAS,IAAI,IAAI,UAAU,CAAC,CAAC,YAAY,CAAC;GAChD,aAAkB,OAAO,CAAC,CAAC,MAAM,YAAY;IAC5C,IAAI,WAAW;KACd,QAAQ,MAAM;KACd;IACD;IACA,KAAK;IACL,IAAI,QAAQ,SAAS,mBAAmB,QAAQ,OAAO;IACvD,MAAM,SAAS,eAAe,eAAe,QAAQ,IAAI;IACzD,OAAO,SAAS;IAChB,MAAM,SAAS,QAAQ,IAAI,QAAQ;KAClC,WAAW,IAAI,QAAQ;KACvB,SAAS,EAAE,OAAO;IACnB,CAAC;IACD,IAAI,OAAO,WAAW,SAAS,WAAW,OAAO,KAAK;GACvD,GAAG,UAAU;GACb,aAAa;IACZ,YAAY;IACZ,IAAI,MAAM;IACV,KAAK,MAAM,SAAS,UAAU,CAAC,CAAC,YAAY,GAC3C,IAAI,CAAC,OAAO,IAAI,KAAK,GAAG,MAAM,QAAQ;GAExC;EACD,GAAG,CAAC,GAAG,CAAC;EAER,OAAO,cAAc,aAAa;GACjC,KAAK;GACL,MAAM,QAAQ;GACd,cAAc;EACf,CAAC;CACF;CACA,WAAW,cAAc,cAAc,QAAQ,KAAK;CACpD,OAAO;EAAE,OAAO,QAAQ,SAAS,QAAQ;EAAM,QAAQ;CAAW;AACnE"}