runmat 0.3.6 → 0.4.0

package/dist/generated/builtins/pad.js

@@ -0,0 +1,182 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "pad",
+    "category": "strings/transform",
+    "keywords": [
+        "pad",
+        "pad string",
+        "left pad",
+        "right pad",
+        "center text",
+        "character arrays"
+    ],
+    "summary": "Pad strings, character arrays, and cell arrays to a target length using MATLAB-compatible options.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/pad.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Executes on the CPU; GPU-resident inputs are gathered before padding so behaviour matches MATLAB."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::strings::transform::pad::tests",
+        "integration": "builtins::strings::transform::pad::tests::pad_cell_array_mixed_content"
+    },
+    "description": "`pad` adds characters to the beginning, end, or both sides of strings so that each element reaches a specified length. It mirrors MATLAB semantics for string arrays, character arrays, and cell arrays of character vectors, including direction keywords, default space padding, and optional custom characters.",
+    "behaviors": [
+        "Without a target length, `pad` extends each element to match the longest text in the input.",
+        "Providing a numeric target guarantees a minimum length; existing text that already meets or exceeds the target is returned unchanged.",
+        "Direction keywords (`'left'`, `'right'`, `'both'`) are case-insensitive; `'right'` is the default. When an odd number of pad characters is required for `'both'`, the extra character is appended to the end.",
+        "`padChar` must be a single character (string scalar or 1×1 char array). The default is a space.",
+        "Character arrays remain rectangular. Each row is padded independently and then widened with spaces so the array keeps MATLAB’s column-major layout.",
+        "Cell arrays preserve their structure. Elements must be string scalars or 1×N character vectors and are padded while keeping their original type.",
+        "Missing strings (`string(missing)`) and empty character vectors pass through unchanged, preserving metadata."
+    ],
+    "examples": [
+        {
+            "description": "Pad Strings To A Common Width",
+            "input": "labels = [\"GPU\"; \"Accelerate\"; \"RunMat\"];\naligned = pad(labels)",
+            "output": "aligned =\n  3×1 string\n    \"GPU       \"\n    \"Accelerate\"\n    \"RunMat    \""
+        },
+        {
+            "description": "Pad Strings On The Left With Zeros",
+            "input": "ids = [\"42\"; \"7\"; \"512\"];\nzero_padded = pad(ids, 4, 'left', '0')",
+            "output": "zero_padded =\n  3×1 string\n    \"0042\"\n    \"0007\"\n    \"0512\""
+        },
+        {
+            "description": "Center Text With Both-Sided Padding",
+            "input": "titles = [\"core\"; \"planner\"];\ncentered = pad(titles, 10, 'both', '*')",
+            "output": "centered =\n  2×1 string\n    \"***core***\"\n    \"*planner**\""
+        },
+        {
+            "description": "Pad Character Array Rows",
+            "input": "chars = char(\"GPU\", \"RunMat\");\nout = pad(chars, 8)",
+            "output": "out =\n\n  2×8 char array\n\n    'GPU     '\n    'RunMat  '"
+        },
+        {
+            "description": "Pad A Cell Array Of Character Vectors",
+            "input": "C = {'solver', \"planner\", 'jit'};\ncell_out = pad(C, 'right', '.')",
+            "output": "cell_out = 1×3 cell array\n    {'solver.'}    {\"planner\"}    {'jit....'}"
+        },
+        {
+            "description": "Leave Missing Strings Unchanged",
+            "input": "values = [\"RunMat\", \"<missing>\", \"GPU\"];\nkept = pad(values, 8)",
+            "output": "kept =\n  1×3 string\n    \"RunMat  \"    <missing>    \"GPU     \""
+        }
+    ],
+    "faqs": [
+        {
+            "question": "What inputs does `pad` accept?",
+            "answer": "String scalars, string arrays, character arrays, and cell arrays containing string scalars or character vectors. Other types raise MATLAB-compatible errors."
+        },
+        {
+            "question": "How are direction keywords interpreted?",
+            "answer": "`'left'`, `'right'`, and `'both'` are supported (case-insensitive). `'right'` is the default. With `'both'`, extra characters are added to the end when an odd number of padding characters is required."
+        },
+        {
+            "question": "Can I shorten text with `pad`?",
+            "answer": "No. When the existing text is already longer than the requested target length, it is returned unchanged."
+        },
+        {
+            "question": "What happens when I supply a custom padding character?",
+            "answer": "The character must be length one. RunMat repeats it as many times as needed in the specified direction."
+        },
+        {
+            "question": "Do missing strings get padded?",
+            "answer": "Missing strings (`<missing>`) are passed through untouched so downstream code that checks for missing values continues to work."
+        },
+        {
+            "question": "How are cell array elements returned?",
+            "answer": "Each cell retains its type: string scalars remain strings and character vectors remain 1×N character arrays after padding."
+        },
+        {
+            "question": "Does `pad` change the orientation of row or column string arrays?",
+            "answer": "No. The shape of the input array is preserved exactly; only element lengths change."
+        },
+        {
+            "question": "Will `pad` run on the GPU in the future?",
+            "answer": "Possibly, but today it always gathers to the CPU. Providers may add device-side implementations later, and the behaviour documented here will remain the reference."
+        }
+    ],
+    "links": [
+        {
+            "label": "strip",
+            "url": "./strip"
+        },
+        {
+            "label": "strcat",
+            "url": "./strcat"
+        },
+        {
+            "label": "lower",
+            "url": "./lower"
+        },
+        {
+            "label": "upper",
+            "url": "./upper"
+        },
+        {
+            "label": "compose",
+            "url": "./compose"
+        },
+        {
+            "label": "erase",
+            "url": "./erase"
+        },
+        {
+            "label": "eraseBetween",
+            "url": "./erasebetween"
+        },
+        {
+            "label": "extractBetween",
+            "url": "./extractbetween"
+        },
+        {
+            "label": "join",
+            "url": "./join"
+        },
+        {
+            "label": "replace",
+            "url": "./replace"
+        },
+        {
+            "label": "split",
+            "url": "./split"
+        },
+        {
+            "label": "strrep",
+            "url": "./strrep"
+        },
+        {
+            "label": "strtrim",
+            "url": "./strtrim"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/strings/transform/pad.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/strings/transform/pad.rs"
+    },
+    "gpu_residency": "No. Text data in RunMat lives on the host today. If text happens to originate from a GPU computation, `pad` automatically gathers it before padding, so you never have to manage residency manually for this builtin.",
+    "gpu_behavior": [
+        "`pad` always executes on the CPU. When an argument (or a value nested inside a cell array) lives on the GPU, RunMat gathers it, performs the padding step, and produces a host result or re-wraps the padded value inside the cell. No provider hooks exist yet for string padding, so providers and fusion planners treat `pad` as a sink that terminates device residency."
+    ],
+    "key": "pad",
+    "slug": "pad",
+    "categoryPath": [
+        "strings",
+        "transform"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=pad.js.map

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

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

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

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

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

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

package/dist/generated/builtins/pagefun.js

@@ -0,0 +1,125 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "pagefun",
+    "category": "acceleration/gpu",
+    "keywords": [
+        "pagefun",
+        "gpuArray",
+        "batched matrix multiply",
+        "mtimes",
+        "pages"
+    ],
+    "summary": "Apply MATLAB operators page-by-page across higher-dimensional arrays.",
+    "references": [
+        "https://www.mathworks.com/help/parallel-computing/pagefun.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "matlab",
+        "notes": "WGPU provider accelerates batched @mtimes; if no provider hook is present the runtime evaluates on the host and re-uploads numeric results."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 2,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::acceleration::gpu::pagefun::tests",
+        "integration": "builtins::acceleration::gpu::pagefun::tests::pagefun_gpu_roundtrip_mtimes"
+    },
+    "description": "`pagefun(func, A, B, …)` applies the MATLAB operator referenced by `func` to every page of the supplied arrays. Pages are the two leading dimensions of the inputs; the third and higher dimensions index the individual pages. The inputs must agree in all trailing dimensions, allowing singleton expansion.",
+    "behaviors": [
+        "Accepts function handles, builtin names (character vectors or string scalars), and validates that the requested operator is supported.",
+        "The first two dimensions of each input form the matrix operated on by the builtin. Dimensions three and up identify individual pages. Inputs with fewer pages are broadcast so long as the page extent is `1`.",
+        "Any combination of empty matrices and empty page extents produces empty results with MATLAB-compatible shapes.",
+        "When all operands are `gpuArray` values the builtin gathers data to the host if the registered acceleration provider cannot satisfy the request. Uniform numeric results are uploaded back to the GPU so later operations retain residency."
+    ],
+    "examples": [
+        {
+            "description": "Batched matrix multiplication across pages",
+            "input": "A = reshape(1:12, [2 2 3]);\nB = reshape(13:24, [2 2 3]);\nC = pagefun(@mtimes, A, B)",
+            "output": "C(:,:,1) =\n    55    63\n    82    94\n\nC(:,:,2) =\n   211   235\n   246   274\n\nC(:,:,3) =\n   431   471\n   474   518"
+        },
+        {
+            "description": "Broadcasting a single page against multiple pages",
+            "input": "A = reshape(1:8, [2 2 2]);\nB = eye(2);\nC = pagefun(@mtimes, A, B);   % B broadcasts across the page dimension"
+        },
+        {
+            "description": "Working with `gpuArray` inputs",
+            "input": "G1 = gpuArray(rand(4, 4, 8));\nG2 = gpuArray(rand(4, 4, 8));\nH = pagefun(@mtimes, G1, G2);\nfirstPage = gather(H(:, :, 1));   % Inspect the first product page on the host"
+        },
+        {
+            "description": "Handling empty page dimensions",
+            "input": "Z = zeros(2, 2, 0);\nR = pagefun(@mtimes, Z, Z);\nsize(R)",
+            "output": "ans =\n     2     2     0"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Which functions does `pagefun` support today?",
+            "answer": "RunMat currently supports `@mtimes` page-wise. Additional MATLAB page-aware functions will be added over time as the GPU provider hooks land."
+        },
+        {
+            "question": "How are page dimensions inferred?",
+            "answer": "The first two dimensions represent the matrix operated on by the builtin. Any remaining dimensions are treated as page indices. Inputs with fewer trailing dimensions receive implicit singleton expansion to match other operands."
+        },
+        {
+            "question": "What happens if the pages are incompatible?",
+            "answer": "`pagefun` raises a MATLAB-compatible error describing the mismatched page dimension. Matrix dimension mismatches are forwarded from the underlying builtin (for example, `Inner matrix dimensions must agree` for `@mtimes`)."
+        },
+        {
+            "question": "Are results always uploaded back to the GPU?",
+            "answer": "Numeric results are uploaded when every operand started as a `gpuArray` and an acceleration provider is registered. Complex results remain on the host today, matching MATLAB's behaviour when complex GPU buffers are not available."
+        },
+        {
+            "question": "Does `pagefun` participate in fusion?",
+            "answer": "No. Because `pagefun` can invoke arbitrary MATLAB builtins it forms a fusion barrier. Upstream expressions are evaluated before entering `pagefun`."
+        }
+    ],
+    "links": [
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "arrayfun",
+            "url": "./arrayfun"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "gpuDevice",
+            "url": "./gpudevice"
+        },
+        {
+            "label": "gpuInfo",
+            "url": "./gpuinfo"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/acceleration/gpu/pagefun.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/acceleration/gpu/pagefun.rs"
+    },
+    "gpu_residency": "No. RunMat's auto-offload planner migrates tensors to the GPU when beneficial. When you explicitly pass `gpuArray` inputs, `pagefun` keeps numeric results on the device whenever all operands were device-resident and the provider can accept uploads. Complex outputs remain host-resident until device buffers for complex doubles ship.",
+    "gpu_behavior": [
+        "RunMat Accelerate exposes a custom `pagefun` provider hook. When the active provider implements it (the WGPU backend does for `@mtimes`), pages stay on the device and execute via a tiled compute shader. If the provider does not support the requested operator the runtime gathers the data to the host, evaluates using the CPU builtin, and re-uploads numeric outputs so subsequent GPU work can stay resident."
+    ],
+    "key": "pagefun",
+    "slug": "pagefun",
+    "categoryPath": [
+        "acceleration",
+        "gpu"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=pagefun.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pagefun.js","sourceRoot":"","sources":["../../../src/generated/builtins/pagefun.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,uBAAuB;AAIvB,MAAM,UAAU,GAAe;IAC7B,OAAO,EAAE,SAAS;IAClB,UAAU,EAAE,kBAAkB;IAC9B,UAAU,EAAE;QACV,SAAS;QACT,UAAU;QACV,yBAAyB;QACzB,QAAQ;QACR,OAAO;KACR;IACD,SAAS,EAAE,uEAAuE;IAClF,YAAY,EAAE;QACZ,gEAAgE;KACjE;IACD,aAAa,EAAE;QACb,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE;YACZ,KAAK;YACL,KAAK;SACN;QACD,cAAc,EAAE,QAAQ;QACxB,OAAO,EAAE,6IAA6I;KACvJ;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,6CAA6C;QACrD,aAAa,EAAE,2EAA2E;KAC3F;IACD,aAAa,EAAE,iTAAiT;IAChU,WAAW,EAAE;QACX,wIAAwI;QACxI,gNAAgN;QAChN,gHAAgH;QAChH,6OAA6O;KAC9O;IACD,UAAU,EAAE;QACV;YACE,aAAa,EAAE,4CAA4C;YAC3D,OAAO,EAAE,uFAAuF;YAChG,QAAQ,EAAE,4HAA4H;SACvI;QACD;YACE,aAAa,EAAE,mDAAmD;YAClE,OAAO,EAAE,iHAAiH;SAC3H;QACD;YACE,aAAa,EAAE,gCAAgC;YAC/C,OAAO,EAAE,6KAA6K;SACvL;QACD;YACE,aAAa,EAAE,gCAAgC;YAC/C,OAAO,EAAE,2DAA2D;YACpE,QAAQ,EAAE,2BAA2B;SACtC;KACF;IACD,MAAM,EAAE;QACN;YACE,UAAU,EAAE,+CAA+C;YAC3D,QAAQ,EAAE,+IAA+I;SAC1J;QACD;YACE,UAAU,EAAE,mCAAmC;YAC/C,QAAQ,EAAE,qOAAqO;SAChP;QACD;YACE,UAAU,EAAE,6CAA6C;YACzD,QAAQ,EAAE,+NAA+N;SAC1O;QACD;YACE,UAAU,EAAE,8CAA8C;YAC1D,QAAQ,EAAE,uOAAuO;SAClP;QACD;YACE,UAAU,EAAE,uCAAuC;YACnD,QAAQ,EAAE,qJAAqJ;SAChK;KACF;IACD,OAAO,EAAE;QACP;YACE,OAAO,EAAE,UAAU;YACnB,KAAK,EAAE,YAAY;SACpB;QACD;YACE,OAAO,EAAE,UAAU;YACnB,KAAK,EAAE,YAAY;SACpB;QACD;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;KACF;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,kEAAkE;QAC3E,KAAK,EAAE,+GAA+G;KACvH;IACD,eAAe,EAAE,8UAA8U;IAC/V,cAAc,EAAE;QACd,wZAAwZ;KACzZ;IACD,KAAK,EAAE,SAAS;IAChB,MAAM,EAAE,SAAS;IACjB,cAAc,EAAE;QACd,cAAc;QACd,KAAK;KACN;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

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

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

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

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

package/dist/generated/builtins/path.js

@@ -0,0 +1,202 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "path",
+    "category": "io/repl_fs",
+    "keywords": [
+        "path",
+        "search path",
+        "matlab path",
+        "addpath",
+        "rmpath"
+    ],
+    "summary": "Query or replace the MATLAB search path used by RunMat.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/path.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Runs entirely on the CPU. gpuArray text inputs are gathered automatically before processing."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 2,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::io::repl_fs::path::tests",
+        "integration": "builtins::io::repl_fs::path::tests::path_updates_search_directories"
+    },
+    "description": "`path` reads or rewrites the MATLAB search path string that RunMat uses when resolving scripts, functions, and data files. The value mirrors MATLAB's notion of the path: a character row vector whose entries are separated by the platform-specific `pathsep` character.",
+    "behaviors": [
+        "`path()` (no inputs) returns the current search path as a character row vector. Each directory is separated by `pathsep` (`;` on Windows, `:` on Linux/macOS). The current working folder (`pwd`) is implicit and therefore is not included in the string.",
+        "`old = path(newPath)` replaces the stored path with `newPath` and returns the previous value so it can be restored later. `newPath` may be a character row vector, a string scalar, or a 1-by-N double array of character codes. Whitespace at the ends of entries is preserved, matching MATLAB.",
+        "`old = path(path1, path2)` sets the path to `path1` followed by `path2`. When both inputs are non-empty they are joined with `pathsep`; empty inputs are ignored so `path(\"\", path2)` simply applies `path2`.",
+        "All inputs must be character vectors or string scalars. Single-element string arrays are accepted. Multirow char arrays, multi-element string arrays, numeric arrays that cannot be interpreted as character codes, and other value types raise `path: arguments must be character vectors or string scalars`.",
+        "Calling `path(\"\")` clears the stored path while leaving `pwd` as the highest-priority location, just like MATLAB. The new value is stored in-process and mirrored to the `RUNMAT_PATH` environment variable, so `exist`, `which`, `dir`, and other filesystem-aware builtins observe the change immediately."
+    ],
+    "examples": [
+        {
+            "description": "Display the current MATLAB search path",
+            "input": "p = path();\ndisp(p)",
+            "output": "//runmat/toolbox://runmat/user"
+        },
+        {
+            "description": "Temporarily replace the MATLAB path",
+            "input": "old = path(\"//runmat-addons\");\n% ... run code that relies on the temporary path ...\npath(old);   % Restore the previous path",
+            "output": "old =\n    '//runmat/toolbox://runmat/user'"
+        },
+        {
+            "description": "Append folders to the end of the search path",
+            "input": "extra = \"//projects/analysis\";\npath(path(), extra);\npath()",
+            "output": "ans =\n    '//runmat/toolbox://runmat/user://projects/analysis'"
+        },
+        {
+            "description": "Prepend folders ahead of the existing path",
+            "input": "extra = \"/opt/runmat/toolbox\";\npath(extra, path());\npath()",
+            "output": "ans =\n    '/opt/runmat/toolbox://runmat/toolbox://runmat/user'"
+        },
+        {
+            "description": "Combine generated folder lists",
+            "input": "tooling = genpath(\"submodules/tooling\");\nold = path(tooling, path())",
+            "output": "% The directories returned by genpath now appear ahead of the previous path entries."
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `path` include the current folder?",
+            "answer": "MATLAB automatically searches the current folder (`pwd`) before consulting the stored path. RunMat follows this rule; the character vector returned by `path` reflects the explicit path entries, while `pwd` remains an implicit priority."
+        },
+        {
+            "question": "Can I clear the path completely?",
+            "answer": "Yes. Call `path(\"\")` to remove all explicit entries. The current folder is still searched first."
+        },
+        {
+            "question": "How do I append to the path without losing the existing value?",
+            "answer": "Use `path(path(), newEntry)` to append or `path(newEntry, path())` to prepend. Both return the previous value so you can restore it later."
+        },
+        {
+            "question": "Where is the path stored?",
+            "answer": "RunMat keeps the value in memory and updates the `RUNMAT_PATH` environment variable. External tooling that reads `RUNMAT_PATH` will therefore observe the latest configuration."
+        },
+        {
+            "question": "Do other builtins see the new path immediately?",
+            "answer": "Yes. `exist`, `which`, `run`, and other filesystem-aware builtins query the shared path state on each call."
+        }
+    ],
+    "links": [
+        {
+            "label": "addpath",
+            "url": "./addpath"
+        },
+        {
+            "label": "rmpath",
+            "url": "./rmpath"
+        },
+        {
+            "label": "genpath",
+            "url": "./genpath"
+        },
+        {
+            "label": "which",
+            "url": "./which"
+        },
+        {
+            "label": "exist",
+            "url": "./exist"
+        },
+        {
+            "label": "addpath",
+            "url": "./addpath"
+        },
+        {
+            "label": "cd",
+            "url": "./cd"
+        },
+        {
+            "label": "copyfile",
+            "url": "./copyfile"
+        },
+        {
+            "label": "delete",
+            "url": "./delete"
+        },
+        {
+            "label": "dir",
+            "url": "./dir"
+        },
+        {
+            "label": "fullfile",
+            "url": "./fullfile"
+        },
+        {
+            "label": "genpath",
+            "url": "./genpath"
+        },
+        {
+            "label": "getenv",
+            "url": "./getenv"
+        },
+        {
+            "label": "ls",
+            "url": "./ls"
+        },
+        {
+            "label": "mkdir",
+            "url": "./mkdir"
+        },
+        {
+            "label": "movefile",
+            "url": "./movefile"
+        },
+        {
+            "label": "pwd",
+            "url": "./pwd"
+        },
+        {
+            "label": "rmdir",
+            "url": "./rmdir"
+        },
+        {
+            "label": "rmpath",
+            "url": "./rmpath"
+        },
+        {
+            "label": "savepath",
+            "url": "./savepath"
+        },
+        {
+            "label": "setenv",
+            "url": "./setenv"
+        },
+        {
+            "label": "tempdir",
+            "url": "./tempdir"
+        },
+        {
+            "label": "tempname",
+            "url": "./tempname"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/io/repl_fs/path.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/io/repl_fs/path.rs"
+    },
+    "gpu_residency": "No. The MATLAB path is a host-only configuration. RunMat automatically gathers any `gpuArray` text inputs, applies the request on the CPU, and returns the result as a character array. Explicitly creating `gpuArray` strings provides no benefit.",
+    "gpu_behavior": [
+        "`path` operates entirely on host-side state. If an argument lives on the GPU, RunMat gathers it back to the CPU before validation. No acceleration provider hooks are required and no GPU kernels are launched."
+    ],
+    "key": "path",
+    "slug": "path",
+    "categoryPath": [
+        "io",
+        "repl_fs"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=path.js.map

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

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

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

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

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

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