runmat 0.3.6 → 0.4.0

package/dist/generated/builtins/getenv.d.ts

@@ -0,0 +1,4 @@
+import type { BuiltinDoc } from "../../builtins.js";
+declare const builtinDoc: BuiltinDoc;
+export default builtinDoc;
+//# sourceMappingURL=getenv.d.ts.map

package/dist/generated/builtins/getenv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getenv.d.ts","sourceRoot":"","sources":["../../../src/generated/builtins/getenv.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,QAAA,MAAM,UAAU,EAAE,UA4MjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/generated/builtins/getenv.js

@@ -0,0 +1,209 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "getenv",
+    "category": "io/repl_fs",
+    "keywords": [
+        "getenv",
+        "environment variable",
+        "env",
+        "system variable",
+        "process environment"
+    ],
+    "summary": "Query environment variables as character vectors, strings, or structures.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/getenv.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Host-only operation. RunMat gathers GPU-resident arguments before querying the process environment; providers do not implement hooks for this builtin."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::io::repl_fs::getenv::tests",
+        "integration": "builtins::io::repl_fs::getenv::tests::getenv_returns_struct_with_all_variables"
+    },
+    "description": "`getenv` reads environment variables that are visible to the current process. When you call `getenv(\"NAME\")`, the builtin returns the value of the environment variable `NAME`, matching MATLAB behaviour. Supplying no input arguments returns a struct where each field corresponds to an environment variable.",
+    "behaviors": [
+        "Accepts character vectors (`'PATH'`) or string scalars (`\"PATH\"`). Character vector inputs return character vectors; string inputs return string scalars.",
+        "Vectorised calls are supported: pass a string array to receive a string array of values, or a cell array of character vectors to receive a cell array of character vectors.",
+        "When the requested variable is not defined, `getenv` returns an empty character vector or an empty string scalar (depending on the input type). This matches MATLAB’s “variable not found” semantics.",
+        "Calling `getenv` with no arguments returns a scalar struct. Field names are the environment variable names; field values are character vectors containing each variable’s value.",
+        "On Windows, environment variable lookups are case-insensitive, mirroring the operating system. On Unix-like systems, lookups are case-sensitive.",
+        "Trailing spaces in character matrix inputs are ignored so that padded rows created with MATLAB’s string manipulation functions remain compatible.",
+        "The builtin rejects non-text inputs (numeric arrays, logicals, GPU tensors, etc.) with a clear MATLAB-style diagnostic."
+    ],
+    "examples": [
+        {
+            "description": "Read A Single Environment Variable",
+            "input": "homeFolder = getenv(\"HOME\");\ndisp(homeFolder)",
+            "output": "homeFolder =\n    \"/\""
+        },
+        {
+            "description": "Handle Missing Environment Variables",
+            "input": "token = getenv(\"RUNMAT_TOKEN\");\nif token == \"\"\n    warning(\"Token not configured.\");\nend",
+            "output": "Warning: Token not configured."
+        },
+        {
+            "description": "Fetch Multiple Variables With A String Array",
+            "input": "vars = getenv([\"PATH\", \"SHELL\"]);\ndisp(vars)",
+            "output": "vars = 1x2 string\n    \"/usr/local/bin:/usr/bin:/bin\"    \"/bin/sh\""
+        },
+        {
+            "description": "Use A Cell Array Of Character Vectors",
+            "input": "cells = getenv({'HOME', 'PATH'});\ndisp(cells{1})",
+            "output": "/"
+        },
+        {
+            "description": "Inspect All Environment Variables",
+            "input": "env = getenv();\ndisp(env.USER)",
+            "output": "env =\n  struct with fields:\n    HOME: '/'\n    PATH: '/usr/local/bin:/usr/bin:/bin'\n    USER: 'user'"
+        },
+        {
+            "description": "Cache The Environment For Repeated Access",
+            "input": "env = getenv();\nresultsFolder = fullfile(env.HOME, \"results\")",
+            "output": "resultsFolder =\n    \"//results\""
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What does `getenv` return when the variable is missing?",
+            "answer": "An empty character vector (`''`) for character inputs, or an empty string scalar (`\"\"`) for string inputs. You can test for a missing variable with `isempty(value)` or `value == \"\"`."
+        },
+        {
+            "question": "Does `getenv` support vectorised inputs?",
+            "answer": "Yes. Pass a string array or a cell array of character vectors to retrieve multiple values in one call. The output mirrors the input container type."
+        },
+        {
+            "question": "Are environment variable lookups case-sensitive?",
+            "answer": "RunMat follows the operating system. Lookups are case-insensitive on Windows and case-sensitive on Unix-like systems, matching MATLAB."
+        },
+        {
+            "question": "Does `getenv` modify the environment?",
+            "answer": "No. It is a read-only operation. Use the forthcoming `setenv` builtin to modify the environment once it is available."
+        },
+        {
+            "question": "Can I call `getenv` from GPU-accelerated code?",
+            "answer": "Yes. Inputs originating on the GPU are gathered automatically. The builtin still executes on the CPU, and the output lives on the host."
+        },
+        {
+            "question": "How do I access all environment variables at once?",
+            "answer": "Call `getenv()` with no arguments. The result is a struct whose fields contain character vectors for each environment variable."
+        },
+        {
+            "question": "What happens if an environment variable name is not a valid struct field?",
+            "answer": "RunMat preserves the exact name as a struct field. Access it via dynamic field references when the name contains characters that cannot be used in dot notation."
+        },
+        {
+            "question": "Are trailing spaces in character inputs significant?",
+            "answer": "No. Trailing spaces introduced by padding character matrices are stripped before the lookup so that MATLAB-style character arrays work as expected."
+        },
+        {
+            "question": "Does `getenv` include inherited environment variables?",
+            "answer": "Yes. The builtin reports every variable visible to the RunMat process, including inherited values."
+        }
+    ],
+    "links": [
+        {
+            "label": "tempdir",
+            "url": "./tempdir"
+        },
+        {
+            "label": "tempname",
+            "url": "./tempname"
+        },
+        {
+            "label": "pwd",
+            "url": "./pwd"
+        },
+        {
+            "label": "path",
+            "url": "./path"
+        },
+        {
+            "label": "addpath",
+            "url": "./addpath"
+        },
+        {
+            "label": "cd",
+            "url": "./cd"
+        },
+        {
+            "label": "copyfile",
+            "url": "./copyfile"
+        },
+        {
+            "label": "delete",
+            "url": "./delete"
+        },
+        {
+            "label": "dir",
+            "url": "./dir"
+        },
+        {
+            "label": "exist",
+            "url": "./exist"
+        },
+        {
+            "label": "fullfile",
+            "url": "./fullfile"
+        },
+        {
+            "label": "genpath",
+            "url": "./genpath"
+        },
+        {
+            "label": "ls",
+            "url": "./ls"
+        },
+        {
+            "label": "mkdir",
+            "url": "./mkdir"
+        },
+        {
+            "label": "movefile",
+            "url": "./movefile"
+        },
+        {
+            "label": "rmdir",
+            "url": "./rmdir"
+        },
+        {
+            "label": "rmpath",
+            "url": "./rmpath"
+        },
+        {
+            "label": "savepath",
+            "url": "./savepath"
+        },
+        {
+            "label": "setenv",
+            "url": "./setenv"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/io/repl_fs/getenv.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/io/repl_fs/getenv.rs"
+    },
+    "gpu_residency": "No. `getenv` has no GPU implementation and simply queries the host environment. Passing GPU-resident values is supported (RunMat gathers them automatically), but there is no benefit to calling `gpuArray` yourself.",
+    "gpu_behavior": [
+        "`getenv` always runs on the CPU. If the argument originates from the GPU—for example, a string scalar produced by an accelerated builtin—RunMat gathers it to host memory before reading the environment. No GPU kernels are launched, and acceleration providers do not need to implement hooks for this builtin."
+    ],
+    "key": "getenv",
+    "slug": "getenv",
+    "categoryPath": [
+        "io",
+        "repl_fs"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=getenv.js.map

package/dist/generated/builtins/getenv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getenv.js","sourceRoot":"","sources":["../../../src/generated/builtins/getenv.ts"],"names":[],"mappings":"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"}

package/dist/generated/builtins/getfield.d.ts

@@ -0,0 +1,4 @@
+import type { BuiltinDoc } from "../../builtins.js";
+declare const builtinDoc: BuiltinDoc;
+export default builtinDoc;
+//# sourceMappingURL=getfield.d.ts.map

package/dist/generated/builtins/getfield.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getfield.d.ts","sourceRoot":"","sources":["../../../src/generated/builtins/getfield.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,QAAA,MAAM,UAAU,EAAE,UAkJjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/generated/builtins/getfield.js

@@ -0,0 +1,151 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "getfield",
+    "category": "structs/core",
+    "keywords": [
+        "getfield",
+        "struct",
+        "struct array",
+        "object property",
+        "metadata"
+    ],
+    "summary": "Access a field or property from structs, struct arrays, or MATLAB-style objects.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Runs on the host. Values that already reside on the GPU stay resident; no kernels are dispatched."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::structs::core::getfield::tests",
+        "integration": "runmat_ignition::tests::functions::member_get_set_and_method_call_skeleton"
+    },
+    "description": "`value = getfield(S, field)` returns the contents of `S.field`. RunMat matches MATLAB by supporting nested field access, struct arrays (via index cells), and MATLAB-style objects created with `new_object`.",
+    "behaviors": [
+        "Field names must be character vectors or string scalars. Several field names in a row navigate nested structs: `getfield(S, \"outer\", \"inner\")` is equivalent to `S.outer.inner`.",
+        "When `S` is a struct array, `getfield(S, \"field\")` examines the first element by default. Provide indices in a cell array to target another element: `getfield(S, {k}, \"field\")` yields `S(k).field`.",
+        "After a field name you may supply an index cell to subscript the field value, e.g. `getfield(S, \"values\", {row, col})`. Each position accepts positive integers or the keyword `end` to reference the last element in that dimension.",
+        "MATLAB-style objects honour property attributes: static or private properties raise errors, while dependent properties invoke `get.<name>` when available.",
+        "Handle objects dereference to their underlying instance automatically. Deleted handles raise the standard MATLAB-style error.",
+        "`MException` values expose the `message`, `identifier`, and `stack` fields for compatibility with MATLAB error handling."
+    ],
+    "examples": [
+        {
+            "description": "Reading a scalar struct field",
+            "input": "stats = struct(\"mean\", 42, \"stdev\", 3.5);\nmu = getfield(stats, \"mean\")",
+            "output": "mu = 42"
+        },
+        {
+            "description": "Navigating nested structs with multiple field names",
+            "input": "cfg = struct(\"solver\", struct(\"name\", \"cg\", \"tolerance\", 1e-6));\ntol = getfield(cfg, \"solver\", \"tolerance\")",
+            "output": "tol = 1.0000e-06"
+        },
+        {
+            "description": "Accessing an element of a struct array",
+            "input": "people = struct(\"name\", {\"Ada\", \"Grace\"}, \"id\", {101, 102});\nlastId = getfield(people, {2}, \"id\")",
+            "output": "lastId = 102"
+        },
+        {
+            "description": "Reading the first element of a struct array automatically",
+            "input": "people = struct(\"name\", {\"Ada\", \"Grace\"}, \"id\", {101, 102});\nfirstName = getfield(people, \"name\")",
+            "output": "firstName = \"Ada\""
+        },
+        {
+            "description": "Using `end` to reference the last item in a field",
+            "input": "series = struct(\"values\", {1:5});\nlastValue = getfield(series, \"values\", {\"end\"})",
+            "output": "lastValue = 5"
+        },
+        {
+            "description": "Indexing into a numeric field value",
+            "input": "measurements = struct(\"values\", {[1 2 3; 4 5 6]});\nentry = getfield(measurements, \"values\", {2, 3})",
+            "output": "entry = 6"
+        },
+        {
+            "description": "Gathering the exception message from a try/catch block",
+            "input": "try\n    error(\"RunMat:domainError\", \"Bad input\");\ncatch e\n    msg = getfield(e, \"message\");\nend",
+            "output": "msg = 'Bad input'"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `getfield` work on non-struct values?",
+            "answer": "No. The first argument must be a scalar struct, a struct array (possibly empty), an object instance created with `new_object`, a handle object, or an `MException`. Passing other types raises an error."
+        },
+        {
+            "question": "How do I access nested struct fields?",
+            "answer": "Provide every level explicitly: `getfield(S, \"parent\", \"child\", \"leaf\")` traverses the same path as `S.parent.child.leaf`."
+        },
+        {
+            "question": "How do I read from a struct array?",
+            "answer": "Supply a cell array of indices before the first field name. For example, `getfield(S, {3}, \"value\")` mirrors `S(3).value`. Indices are one-based like MATLAB."
+        },
+        {
+            "question": "Can I index the value stored in a field?",
+            "answer": "Yes. You may supply scalars or `end` inside the index cell to reference elements of the field value."
+        },
+        {
+            "question": "Do dependent properties run their getter methods?",
+            "answer": "Yes. If a property is marked `Dependent` and a `get.propertyName` builtin exists, `getfield` invokes it. Otherwise the backing field `<property>_backing` is inspected."
+        },
+        {
+            "question": "What happens when I query a deleted handle object?",
+            "answer": "RunMat mirrors MATLAB by raising `Invalid or deleted handle object 'ClassName'.`"
+        }
+    ],
+    "links": [
+        {
+            "label": "fieldnames",
+            "url": "./fieldnames"
+        },
+        {
+            "label": "isfield",
+            "url": "./isfield"
+        },
+        {
+            "label": "setfield",
+            "url": "./setfield"
+        },
+        {
+            "label": "struct",
+            "url": "./struct"
+        },
+        {
+            "label": "class",
+            "url": "./class"
+        },
+        {
+            "label": "orderfields",
+            "url": "./orderfields"
+        },
+        {
+            "label": "rmfield",
+            "url": "./rmfield"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/structs/core/getfield.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/structs/core/getfield.rs"
+    },
+    "gpu_residency": "You do not have to move data between CPU and GPU explicitly when calling `getfield`. The builtin works entirely with metadata and returns handles or tensors in whatever memory space they already inhabit.",
+    "gpu_behavior": [
+        "`getfield` is metadata-only. When structs or objects contain GPU tensors, the tensors remain on the device. The builtin manipulates only the host-side metadata and does not dispatch GPU kernels or gather buffers back to the CPU. Results inherit residency from the values being returned."
+    ],
+    "key": "getfield",
+    "slug": "getfield",
+    "categoryPath": [
+        "structs",
+        "core"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=getfield.js.map

package/dist/generated/builtins/getfield.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getfield.js","sourceRoot":"","sources":["../../../src/generated/builtins/getfield.ts"],"names":[],"mappings":"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"}

package/dist/generated/builtins/gpuArray.d.ts

@@ -0,0 +1,4 @@
+import type { BuiltinDoc } from "../../builtins.js";
+declare const builtinDoc: BuiltinDoc;
+export default builtinDoc;
+//# sourceMappingURL=gpuArray.d.ts.map

package/dist/generated/builtins/gpuArray.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpuArray.d.ts","sourceRoot":"","sources":["../../../src/generated/builtins/gpuArray.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,QAAA,MAAM,UAAU,EAAE,UAgIjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/generated/builtins/gpuArray.js

@@ -0,0 +1,133 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "gpuArray",
+    "category": "acceleration/gpu",
+    "keywords": [
+        "gpuArray",
+        "gpu",
+        "device",
+        "upload",
+        "accelerate",
+        "dtype",
+        "like",
+        "size"
+    ],
+    "summary": "Move MATLAB values onto the active GPU with optional size, dtype, and prototype controls.",
+    "references": [
+        "https://www.mathworks.com/help/parallel-computing/gpuarray.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "none",
+        "notes": "Uploads host-resident data through the provider `upload` hook, re-uploading gpuArray inputs when dtype conversion is requested. Supports MATLAB-style size vectors, class strings, and `'like'` prototypes."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::acceleration::gpu::gpuarray::tests",
+        "integration": "builtins::acceleration::gpu::gpuarray::tests::gpu_array_transfers_numeric_tensor",
+        "conversions": "builtins::acceleration::gpu::gpuarray::tests::gpu_array_casts_to_int32",
+        "reshape": "builtins::acceleration::gpu::gpuarray::tests::gpu_array_applies_size_arguments",
+        "wgpu": "builtins::acceleration::gpu::gpuarray::tests::gpu_array_wgpu_roundtrip"
+    },
+    "description": "`gpuArray(X)` moves MATLAB values onto the active GPU and returns a handle that the rest of the runtime can execute on. RunMat mirrors MATLAB semantics, including MATLAB-style size arguments, explicit dtype toggles (such as `'single'`, `'int32'`, `'logical'`), and the `'like'` prototype syntax that matches the class of an existing array.",
+    "behaviors": [
+        "Accepts numeric tensors, logical arrays, booleans, character vectors, and existing gpuArray handles. Other input types raise descriptive errors so callers can gather or convert first.",
+        "Optional leading size arguments (`gpuArray(data, m, n, ...)` or `gpuArray(data, [m n ...])`) reshape the uploaded value. The element count must match the requested size.",
+        "Class strings such as `'single'`, `'double'`, `'int32'`, `'uint8'`, and `'logical'` convert the data before upload, matching MATLAB casting semantics (round-to-nearest with saturation for integers, `NaN`→0 for integer classes, and errors when converting `NaN` to logical).",
+        "`'like', prototype` infers the dtype (and logical state) from `prototype`. Explicit class strings override the inference when both are supplied.",
+        "`\"gpuArray\"` strings are accepted as no-ops so call-sites that forward arguments from constructors such as `zeros(..., 'gpuArray')` remain compatible.",
+        "Inputs that are already gpuArray handles pass through by default. When a class change is requested, RunMat gathers the data, performs the conversion, uploads a fresh buffer, and frees the old handle.",
+        "When no acceleration provider is registered, the builtin raises `gpuArray: no acceleration provider registered`."
+    ],
+    "examples": [
+        {
+            "description": "Moving a matrix to the GPU for elementwise work",
+            "input": "A = [1 2 3; 4 5 6];\nG = gpuArray(A);\nout = gather(sin(G))",
+            "output": "out =\n  2×3\n\n    0.8415    0.9093    0.1411\n   -0.7568   -0.9589   -0.2794"
+        },
+        {
+            "description": "Uploading a scalar with dtype conversion",
+            "input": "pi_single = gpuArray(pi, 'single');\nisa(pi_single, 'gpuArray');\nclass(gather(pi_single))",
+            "output": "ans =\n  logical\n     1\n\nans =\n  single"
+        },
+        {
+            "description": "Converting host data to a logical gpuArray",
+            "input": "mask = gpuArray([0 2 -5 0], 'logical');\ngather(mask)",
+            "output": "ans =\n  1×4 logical array\n\n   0   1   1   0"
+        },
+        {
+            "description": "Matching an existing prototype with `'like'`",
+            "input": "template = gpuArray(true(2, 2));\nvalues = gpuArray([10 20 30 40], [2 2], 'like', template);\nisequal(gather(values), logical([10 20; 30 40]))",
+            "output": "ans =\n  logical\n     1"
+        },
+        {
+            "description": "Reshaping during upload",
+            "input": "flat = 1:6;\nG = gpuArray(flat, 2, 3);\nsize(G)",
+            "output": "ans =\n     2     3"
+        },
+        {
+            "description": "Calling `gpuArray` on an existing gpuArray handle",
+            "input": "G = gpuArray([1 2 3]);\nH = gpuArray(G, 'double');\nisequal(G, H)",
+            "output": "ans =\n  logical\n     1"
+        }
+    ],
+    "faqs": [],
+    "links": [
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "gpuDevice",
+            "url": "./gpudevice"
+        },
+        {
+            "label": "gpuInfo",
+            "url": "./gpuinfo"
+        },
+        {
+            "label": "arrayfun",
+            "url": "./arrayfun"
+        },
+        {
+            "label": "zeros",
+            "url": "./zeros"
+        },
+        {
+            "label": "sum",
+            "url": "./sum"
+        },
+        {
+            "label": "pagefun",
+            "url": "./pagefun"
+        }
+    ],
+    "source": {
+        "label": "crates/runmat-runtime/src/builtins/acceleration/gpu/gpuarray.rs",
+        "url": "crates/runmat-runtime/src/builtins/acceleration/gpu/gpuarray.rs"
+    },
+    "gpu_residency": "RunMat’s auto-offload planner transparently moves and keeps tensors on the GPU when it predicts a benefit. You typically call `gpuArray` to honour MATLAB scripts that opt-in explicitly, to enforce residency before a long computation, or when you need MATLAB-style dtype conversion alongside the upload. The builtin never forces a host copy once the handle has been created.",
+    "gpu_behavior": [
+        "`gpuArray` itself runs on the CPU. For host inputs it prepares a `HostTensorView` and forwards it to the provider’s `upload` hook. For gpuArray inputs that require dtype conversion, the builtin gathers the existing buffer, casts the result on the host, uploads a replacement, and frees the original handle. Providers that do not yet implement `upload` should report an informative error; the builtin surface mirrors MATLAB’s message by prefixing it with `gpuArray:`."
+    ],
+    "key": "gpuarray",
+    "slug": "gpuarray",
+    "categoryPath": [
+        "acceleration",
+        "gpu"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=gpuArray.js.map

package/dist/generated/builtins/gpuArray.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpuArray.js","sourceRoot":"","sources":["../../../src/generated/builtins/gpuArray.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,uBAAuB;AAIvB,MAAM,UAAU,GAAe;IAC7B,OAAO,EAAE,UAAU;IACnB,UAAU,EAAE,kBAAkB;IAC9B,UAAU,EAAE;QACV,UAAU;QACV,KAAK;QACL,QAAQ;QACR,QAAQ;QACR,YAAY;QACZ,OAAO;QACP,MAAM;QACN,MAAM;KACP;IACD,SAAS,EAAE,2FAA2F;IACtG,YAAY,EAAE;QACZ,iEAAiE;KAClE;IACD,aAAa,EAAE;QACb,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE;YACZ,KAAK;YACL,KAAK;SACN;QACD,cAAc,EAAE,MAAM;QACtB,OAAO,EAAE,6MAA6M;KACvN;IACD,QAAQ,EAAE;QACR,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE,CAAC;QACf,WAAW,EAAE,QAAQ;KACtB;IACD,kBAAkB,EAAE,IAAI;IACxB,QAAQ,EAAE;QACR,MAAM,EAAE,8CAA8C;QACtD,aAAa,EAAE,kFAAkF;QACjG,aAAa,EAAE,wEAAwE;QACvF,SAAS,EAAE,gFAAgF;QAC3F,MAAM,EAAE,wEAAwE;KACjF;IACD,aAAa,EAAE,qVAAqV;IACpW,WAAW,EAAE;QACX,yLAAyL;QACzL,2KAA2K;QAC3K,kRAAkR;QAClR,kJAAkJ;QAClJ,0JAA0J;QAC1J,yMAAyM;QACzM,kHAAkH;KACnH;IACD,UAAU,EAAE;QACV;YACE,aAAa,EAAE,iDAAiD;YAChE,OAAO,EAAE,6DAA6D;YACtE,QAAQ,EAAE,gFAAgF;SAC3F;QACD;YACE,aAAa,EAAE,0CAA0C;YACzD,OAAO,EAAE,4FAA4F;YACrG,QAAQ,EAAE,6CAA6C;SACxD;QACD;YACE,aAAa,EAAE,4CAA4C;YAC3D,OAAO,EAAE,uDAAuD;YAChE,QAAQ,EAAE,gDAAgD;SAC3D;QACD;YACE,aAAa,EAAE,8CAA8C;YAC7D,OAAO,EAAE,gJAAgJ;YACzJ,QAAQ,EAAE,0BAA0B;SACrC;QACD;YACE,aAAa,EAAE,yBAAyB;YACxC,OAAO,EAAE,iDAAiD;YAC1D,QAAQ,EAAE,qBAAqB;SAChC;QACD;YACE,aAAa,EAAE,mDAAmD;YAClE,OAAO,EAAE,mEAAmE;YAC5E,QAAQ,EAAE,0BAA0B;SACrC;KACF;IACD,MAAM,EAAE,EAAE;IACV,OAAO,EAAE;QACP;YACE,OAAO,EAAE,QAAQ;YACjB,KAAK,EAAE,UAAU;SAClB;QACD;YACE,OAAO,EAAE,WAAW;YACpB,KAAK,EAAE,aAAa;SACrB;QACD;YACE,OAAO,EAAE,SAAS;YAClB,KAAK,EAAE,WAAW;SACnB;QACD;YACE,OAAO,EAAE,UAAU;YACnB,KAAK,EAAE,YAAY;SACpB;QACD;YACE,OAAO,EAAE,OAAO;YAChB,KAAK,EAAE,SAAS;SACjB;QACD;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,OAAO;SACf;QACD;YACE,OAAO,EAAE,SAAS;YAClB,KAAK,EAAE,WAAW;SACnB;KACF;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,iEAAiE;QAC1E,KAAK,EAAE,iEAAiE;KACzE;IACD,eAAe,EAAE,uXAAuX;IACxY,cAAc,EAAE;QACd,odAAod;KACrd;IACD,KAAK,EAAE,UAAU;IACjB,MAAM,EAAE,UAAU;IAClB,cAAc,EAAE;QACd,cAAc;QACd,KAAK;KACN;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/generated/builtins/gpuDevice.d.ts

@@ -0,0 +1,4 @@
+import type { BuiltinDoc } from "../../builtins.js";
+declare const builtinDoc: BuiltinDoc;
+export default builtinDoc;
+//# sourceMappingURL=gpuDevice.d.ts.map

package/dist/generated/builtins/gpuDevice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpuDevice.d.ts","sourceRoot":"","sources":["../../../src/generated/builtins/gpuDevice.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,QAAA,MAAM,UAAU,EAAE,UA0HjB,CAAC;AAEF,eAAe,UAAU,CAAC"}