runmat 0.3.5 → 0.4.0

package/dist/generated/builtins/save.js

@@ -0,0 +1,147 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "save",
+    "category": "io/mat",
+    "keywords": [
+        "save",
+        "mat",
+        "workspace",
+        "io",
+        "matlab save"
+    ],
+    "summary": "Persist variables from the current workspace to a MATLAB-compatible MAT-file.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/save.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "save performs synchronous host I/O. GPU-resident variables are gathered prior to serialisation; no provider hooks are required."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 0,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::io::mat::save::tests",
+        "integration": [
+            "builtins::io::mat::save::tests::save_gpu_tensor_roundtrip",
+            "builtins::io::mat::save::tests::save_wgpu_tensor_roundtrip"
+        ]
+    },
+    "description": "`save` writes variables from the current workspace to a MAT-file on disk. RunMat mirrors MATLAB semantics for choosing variables, handling structs, pattern-based selection via `'-regexp'`, and processing options such as `'-struct'`.",
+    "behaviors": [
+        "`save` with no arguments writes every variable from the caller workspace to `matlab.mat` in the current working directory. Set `RUNMAT_SAVE_DEFAULT_PATH` to override the default target when no filename is supplied.",
+        "`save filename` writes all workspace variables to `filename`. If the supplied name has no extension, `.mat` is added automatically. Paths are resolved relative to the current directory, and parent folders must already exist.",
+        "`save(filename, 'A', 'B')` writes only the listed variables. String arrays or cell arrays of character vectors are accepted to specify multiple names.",
+        "`save(filename, '-struct', 'S')` saves each field of struct `S` as a separate variable. Provide additional field names (`'field1'`, `'field2'`) to restrict the set.",
+        "`save filename -regexp '^foo' 'bar$'` saves every variable whose name matches any of the supplied regular expressions.",
+        "Existing files are overwritten unless `-append` is specified. RunMat currently reports an error when `-append` or other numeric/text format flags (for example `-ascii`, `-double`, `-v6`, `-v7.3`) are requested.",
+        "Unsupported types (function handles, objects, opaque graphics handles) raise descriptive errors. Numeric, logical, character, string, cell, and struct data are stored using MATLAB Level-5 MAT-file layout.",
+        "`save` returns `0` so scripts can treat it as a statement, matching MATLAB's void behaviour."
+    ],
+    "examples": [
+        {
+            "description": "Save the entire workspace",
+            "input": "x = 42;\ny = magic(3);\nsave('session.mat')"
+        },
+        {
+            "description": "Save selected variables only",
+            "input": "a = rand(1, 3);\nb = eye(2);\nc = \"ignore me\";\nsave('selection.mat', 'a', 'b')"
+        },
+        {
+            "description": "Save struct fields as individual variables",
+            "input": "x = 1:5;\ny = rand(1, 5);\nopts = struct('output', y, 'answer', x);\nsave('opts.mat', '-struct', 'opts')"
+        },
+        {
+            "description": "Select variables by regular expression",
+            "input": "result_acc = 1:3;\nresult_tmp = 4:6;\nscratch = pi;\nsave('filtered.mat', '-regexp', '^result_', 'tmp$')"
+        },
+        {
+            "description": "Save multiple names using a string array",
+            "input": "names = [\"result_acc\", \"scratch\"];\nsave('mixed.mat', names)"
+        },
+        {
+            "description": "Save GPU arrays without manual gather",
+            "input": "G = gpuArray(magic(3));\nsave('gpu.mat', 'G')"
+        },
+        {
+            "description": "Error when a variable is missing",
+            "input": "save('bad.mat', 'missing')"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Which MAT-file version is generated?",
+            "answer": "RunMat writes Level-5 (MATLAB 5.0) MAT-files, compatible with MATLAB R2006b and later as well as NumPy/Scipy readers. Structures and cell arrays are stored using standard `miMATRIX` elements."
+        },
+        {
+            "question": "Is `-append` supported?",
+            "answer": "Not yet. The builtin currently reports `save: -append is not supported` to signal the limitation. Future releases will add incremental writing."
+        },
+        {
+            "question": "Do text options like `-ascii` or `-double` work?",
+            "answer": "These legacy text/binary format switches are not supported. RunMat favours MATLAB's default MAT-file format."
+        },
+        {
+            "question": "Are objects or function handles saved?",
+            "answer": "No. RunMat matches MATLAB by raising an error when unsupported types are encountered."
+        },
+        {
+            "question": "Does `save` return a value?",
+            "answer": "Yes. The builtin returns `0`, which MATLAB treats as an empty output, so scripts can ignore the return value just as they do in MATLAB."
+        },
+        {
+            "question": "How do I change the default filename used by bare `save`?",
+            "answer": "Set the environment variable `RUNMAT_SAVE_DEFAULT_PATH` before launching RunMat. When `save` is called without explicit filename arguments, the builtin writes to that path instead of `matlab.mat`."
+        },
+        {
+            "question": "Does `save` create parent directories automatically?",
+            "answer": "No. Parent folders must already exist; otherwise the builtin raises an error from the host filesystem."
+        }
+    ],
+    "links": [
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "fileread",
+            "url": "./fileread"
+        },
+        {
+            "label": "fopen",
+            "url": "./fopen"
+        },
+        {
+            "label": "load",
+            "url": "./load"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/io/mat/save.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/io/mat/save.rs"
+    },
+    "gpu_residency": "No manual action is required. `save` gathers `gpuArray` inputs automatically before writing the MAT-file. This matches MATLAB's behaviour when `gpuArray` variables are passed to `save`.",
+    "gpu_behavior": [
+        "`save` acts as a residency sink. Before serialising, RunMat gathers any GPU-resident tensors through the active acceleration provider so the MAT-file contains host data. Fusion groups terminate at this builtin and providers do not require custom hooks."
+    ],
+    "key": "save",
+    "slug": "save",
+    "categoryPath": [
+        "io",
+        "mat"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=save.js.map

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

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

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

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

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

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

package/dist/generated/builtins/savepath.js

@@ -0,0 +1,220 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "savepath",
+    "category": "io/repl_fs",
+    "keywords": [
+        "savepath",
+        "pathdef",
+        "search path",
+        "runmat path",
+        "persist path"
+    ],
+    "summary": "Persist the current MATLAB search path to pathdef.m with status and diagnostic outputs.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/savepath.html"
+    ],
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [],
+        "broadcasting": "none",
+        "notes": "Runs entirely on the CPU. gpuArray inputs are gathered before resolving the target file."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 1,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::io::repl_fs::savepath::tests",
+        "integration": "builtins::io::repl_fs::savepath::tests::savepath_returns_failure_when_write_fails"
+    },
+    "description": "`savepath` writes the current MATLAB search path to a `pathdef.m` file so that future sessions can restore the same ordering. The file is a MATLAB function that returns the `path` character vector, matching MathWorks MATLAB semantics.",
+    "behaviors": [
+        "`savepath()` with no inputs writes to the default RunMat location (`$HOME/.runmat/pathdef.m` on Linux/macOS, `%USERPROFILE%\\.runmat\\pathdef.m` on Windows). The directory is created automatically when required.",
+        "`savepath(file)` writes to the specified file. Relative paths are resolved against the current working directory, `~` expands to the user's home folder, and supplying a directory (with or without a trailing separator) appends the standard `pathdef.m` filename automatically.",
+        "The function does not modify the in-memory search path - it only writes the current state to disk. Callers can therefore continue editing the path after saving without interference.",
+        "`status = savepath(...)` returns `0` on success and `1` when the file cannot be written. `[status, message, messageID] = savepath(...)` returns MATLAB-style diagnostics describing the failure. Both message outputs are empty on success.",
+        "Invalid argument types raise `savepath: filename must be a character vector or string scalar`. Empty filenames raise `savepath: filename must not be empty`.",
+        "When the `RUNMAT_PATHDEF` environment variable is set, the zero-argument form uses that override instead of the default location."
+    ],
+    "examples": [
+        {
+            "description": "Save The Current Search Path To The Default Location",
+            "input": "status = savepath()",
+            "output": "status =\n     0"
+        },
+        {
+            "description": "Persist A Project-Specific Pathdef File",
+            "input": "status = savepath(\"config/project_pathdef.m\")",
+            "output": "status =\n     0"
+        },
+        {
+            "description": "Capture Status, Message, And Message ID",
+            "input": "[status, message, messageID] = savepath(\"config/pathdef.m\");\nif status ~= 0\n    warning(\"Failed to save the path: %s (%s)\", message, messageID);\nend"
+        },
+        {
+            "description": "Append Genpath Output And Persist The Result",
+            "input": "tooling = genpath(\"third_party/toolchain\");\naddpath(tooling, \"-end\");\nsavepath()"
+        },
+        {
+            "description": "Save A Pathdef Using A Directory Argument",
+            "input": "mkdir(\"~/.runmat/projectA\");\nsavepath(\"~/.runmat/projectA/\")",
+            "output": "% Creates ~/.runmat/projectA/pathdef.m with the current search path."
+        },
+        {
+            "description": "Override The Target File With RUNMAT_PATHDEF",
+            "input": "setenv(\"RUNMAT_PATHDEF\", fullfile(tempdir, \"pathdef-dev.m\"));\nsavepath()",
+            "output": "% The file tempdir/pathdef-dev.m now contains the MATLAB path definition."
+        },
+        {
+            "description": "Use gpuArray Inputs Transparently",
+            "input": "status = savepath(gpuArray(\"pathdefs/pathdef_gpu.m\"))",
+            "output": "status =\n     0"
+        },
+        {
+            "description": "Inspect The Generated pathdef.m File",
+            "input": "savepath(\"toolbox/pathdef.m\");\ntype toolbox/pathdef.m",
+            "output": "% Displays the MATLAB function that reproduces the saved search path."
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Where does `savepath` write by default?",
+            "answer": "RunMat uses `$HOME/.runmat/pathdef.m` (Linux/macOS) or `%USERPROFILE%\\.runmat\\pathdef.m` (Windows). Set `RUNMAT_PATHDEF` to override this location."
+        },
+        {
+            "question": "Does `savepath` create missing folders?",
+            "answer": "Yes. When the parent directory does not exist, RunMat creates it automatically before writing the file."
+        },
+        {
+            "question": "What happens if the file is read-only?",
+            "answer": "`savepath` returns `status = 1` together with the diagnostic message and message ID `RunMat:savepath:cannotWriteFile`. The existing file is left untouched."
+        },
+        {
+            "question": "Does `savepath` modify the current path?",
+            "answer": "No. It only writes out the path. Use `addpath`, `rmpath`, or `path` to change the in-memory value."
+        },
+        {
+            "question": "Are argument types validated?",
+            "answer": "Yes. Inputs must be character vectors or string scalars. String arrays with multiple elements and numeric arrays raise an error."
+        },
+        {
+            "question": "Is the generated file MATLAB-compatible?",
+            "answer": "Yes. RunMat writes a MATLAB function named `pathdef` that returns the exact character vector stored by the `path` builtin, so MathWorks MATLAB and RunMat can both execute it."
+        },
+        {
+            "question": "How do I restore the path later?",
+            "answer": "Evaluate the generated `pathdef.m` (for example by calling `run('~/pathdef.m')`) and pass the returned value to `path()`. Future RunMat releases will load the default file automatically."
+        },
+        {
+            "question": "Can I store multiple path definitions?",
+            "answer": "Absolutely. Call `savepath` with different filenames for each profile, then run the desired file to switch."
+        },
+        {
+            "question": "Is `savepath` safe to call concurrently?",
+            "answer": "The builtin serializes through the filesystem. When multiple sessions write to the same path at once, the last write wins - this matches MATLAB's behavior."
+        },
+        {
+            "question": "Does `savepath` include the current folder (`pwd`)?",
+            "answer": "The file mirrors the output of the `path` builtin, which omits the implicit current folder exactly as MATLAB does."
+        }
+    ],
+    "links": [
+        {
+            "label": "path",
+            "url": "./path"
+        },
+        {
+            "label": "addpath",
+            "url": "./addpath"
+        },
+        {
+            "label": "rmpath",
+            "url": "./rmpath"
+        },
+        {
+            "label": "genpath",
+            "url": "./genpath"
+        },
+        {
+            "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": "getenv",
+            "url": "./getenv"
+        },
+        {
+            "label": "ls",
+            "url": "./ls"
+        },
+        {
+            "label": "mkdir",
+            "url": "./mkdir"
+        },
+        {
+            "label": "movefile",
+            "url": "./movefile"
+        },
+        {
+            "label": "pwd",
+            "url": "./pwd"
+        },
+        {
+            "label": "rmdir",
+            "url": "./rmdir"
+        },
+        {
+            "label": "setenv",
+            "url": "./setenv"
+        },
+        {
+            "label": "tempdir",
+            "url": "./tempdir"
+        },
+        {
+            "label": "tempname",
+            "url": "./tempname"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/io/repl_fs/savepath.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/io/repl_fs/savepath.rs"
+    },
+    "gpu_residency": "No. Because `savepath` interacts with the filesystem, GPU residency provides no benefit. The builtin automatically gathers GPU text inputs so existing scripts continue to work even if they accidentally construct filenames on the device.",
+    "gpu_behavior": [
+        "`savepath` runs entirely on the host. If callers supply a GPU-resident string, RunMat gathers it back to CPU memory before resolving the target path. No acceleration provider hooks or kernels are required."
+    ],
+    "key": "savepath",
+    "slug": "savepath",
+    "categoryPath": [
+        "io",
+        "repl_fs"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=savepath.js.map

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

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

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

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

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

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

package/dist/generated/builtins/scatter.js

@@ -0,0 +1,96 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "scatter",
+    "category": "plotting",
+    "keywords": [
+        "scatter",
+        "scatter plot",
+        "2-D scatter",
+        "marker plot",
+        "matlab scatter",
+        "point cloud visualization"
+    ],
+    "summary": "Create 2-D scatter plots for point clouds, size/color encoding, and MATLAB `scatter` workflows.",
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "single",
+            "double"
+        ],
+        "broadcasting": "none",
+        "notes": "`scatter` is a rendering sink. GPU-resident inputs can stay on device when the shared plotting path can consume exported point buffers directly."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 2,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::plotting::scatter::tests",
+        "integration": "runmat-plot/tests/renderer_tests.rs"
+    },
+    "description": "`scatter` creates 2-D marker plots from paired x and y coordinates. In RunMat it returns a scatter handle, participates in the shared plotting property system, and supports the MATLAB `scatter(x, y, s, c, 'filled')` style of workflows for marker size, marker color, and display-name driven chart composition.",
+    "behaviors": [
+        "`scatter(x, y)` requires the same element count in both inputs.",
+        "The returned value is a scatter-handle object that can be inspected and updated through `get` and `set`.",
+        "Marker size, marker face color, marker edge color, and display name all flow through the shared plotting handle model.",
+        "Scatter plots integrate naturally with `subplot` and `legend`, so series labels and axes-local state stay scoped to the active axes.",
+        "GPU-resident point buffers can be rendered directly on the happy path; unsupported combinations fall back to host materialization while preserving the same visible result."
+    ],
+    "examples": [
+        {
+            "description": "Create a basic 2-D scatter plot",
+            "input": "t = linspace(0, 2*pi, 100);\nscatter(cos(t), sin(t));"
+        },
+        {
+            "description": "Use marker sizing and color-style workflows",
+            "input": "x = linspace(0, 1, 25);\ny = x.^2;\nh = scatter(x, y);\nset(h, 'SizeData', 12, 'MarkerFaceColor', 'r', 'Marker', 'o');"
+        },
+        {
+            "description": "Drive the legend from scatter object display names",
+            "input": "x = 1:10;\nh1 = scatter(x, x);\nset(h1, 'DisplayName', 'linear');\nhold on;\nh2 = scatter(x, x.^2);\nset(h2, 'DisplayName', 'quadratic');\nlegend;"
+        }
+    ],
+    "links": [
+        {
+            "label": "plot",
+            "url": "./plot"
+        },
+        {
+            "label": "scatter3",
+            "url": "./scatter3"
+        },
+        {
+            "label": "legend",
+            "url": "./legend"
+        },
+        {
+            "label": "get",
+            "url": "./get"
+        },
+        {
+            "label": "set",
+            "url": "./set"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/plotting/ops/scatter.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/plotting/ops/scatter.rs"
+    },
+    "gpu_residency": "`scatter` preserves GPU residency when the plotting path can consume exported point buffers directly. If the active marker/style combination cannot use the direct path, RunMat gathers once and renders the same plot semantics on the fallback path.",
+    "gpu_behavior": [
+        "The direct path keeps point buffers on the device and avoids an unnecessary host round-trip for supported scatter workflows.",
+        "Marker styling and legend/display-name behavior stay consistent across GPU and host fallback rendering."
+    ],
+    "key": "scatter",
+    "slug": "scatter",
+    "categoryPath": [
+        "plotting"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=scatter.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scatter.js","sourceRoot":"","sources":["../../../src/generated/builtins/scatter.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,uBAAuB;AAIvB,MAAM,UAAU,GAAe;IAC7B,OAAO,EAAE,SAAS;IAClB,UAAU,EAAE,UAAU;IACtB,UAAU,EAAE;QACV,SAAS;QACT,cAAc;QACd,aAAa;QACb,aAAa;QACb,gBAAgB;QAChB,2BAA2B;KAC5B;IACD,SAAS,EAAE,iGAAiG;IAC5G,aAAa,EAAE;QACb,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE;YACZ,QAAQ;YACR,QAAQ;SACT;QACD,cAAc,EAAE,MAAM;QACtB,OAAO,EAAE,kJAAkJ;KAC5J;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,oCAAoC;QAC5C,aAAa,EAAE,qCAAqC;KACrD;IACD,aAAa,EAAE,sTAAsT;IACrU,WAAW,EAAE;QACX,iEAAiE;QACjE,0GAA0G;QAC1G,wHAAwH;QACxH,sIAAsI;QACtI,6KAA6K;KAC9K;IACD,UAAU,EAAE;QACV;YACE,aAAa,EAAE,iCAAiC;YAChD,OAAO,EAAE,uDAAuD;SACjE;QACD;YACE,aAAa,EAAE,6CAA6C;YAC5D,OAAO,EAAE,wHAAwH;SAClI;QACD;YACE,aAAa,EAAE,oDAAoD;YACnE,OAAO,EAAE,oJAAoJ;SAC9J;KACF;IACD,OAAO,EAAE;QACP;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;QACD;YACE,OAAO,EAAE,UAAU;YACnB,KAAK,EAAE,YAAY;SACpB;QACD;YACE,OAAO,EAAE,QAAQ;YACjB,KAAK,EAAE,UAAU;SAClB;QACD;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,OAAO;SACf;QACD;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,OAAO;SACf;KACF;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,8DAA8D;QACvE,KAAK,EAAE,2GAA2G;KACnH;IACD,eAAe,EAAE,wPAAwP;IACzQ,cAAc,EAAE;QACd,8HAA8H;QAC9H,yGAAyG;KAC1G;IACD,KAAK,EAAE,SAAS;IAChB,MAAM,EAAE,SAAS;IACjB,cAAc,EAAE;QACd,UAAU;KACX;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

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

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

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

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

package/dist/generated/builtins/scatter3.js

@@ -0,0 +1,97 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "scatter3",
+    "category": "plotting",
+    "keywords": [
+        "scatter3",
+        "3-D scatter plot",
+        "point cloud",
+        "matlab scatter3",
+        "spatial data visualization",
+        "gpu plotting"
+    ],
+    "summary": "Create 3-D scatter plots for spatial point clouds, encoded markers, and MATLAB `scatter3` workflows.",
+    "gpu_support": {
+        "elementwise": false,
+        "reduction": false,
+        "precisions": [
+            "single",
+            "double"
+        ],
+        "broadcasting": "none",
+        "notes": "`scatter3` is a rendering sink. GPU inputs can stay resident when the shared plotting device consumes exported buffers directly."
+    },
+    "fusion": {
+        "elementwise": false,
+        "reduction": false,
+        "max_inputs": 3,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::plotting::scatter3::tests",
+        "integration": "runmat-plot/tests/renderer_tests.rs"
+    },
+    "description": "`scatter3` creates 3-D marker plots from matching x, y, and z coordinates. In RunMat it participates in the handle-returning plotting system, which means you can combine it with `subplot`, inspect the figure with `get`, adjust camera angles with `view`, and keep GPU-resident inputs on device when the shared rendering path is available.",
+    "behaviors": [
+        "`scatter3(x, y, z)` requires matching element counts across all three inputs.",
+        "The builtin returns a scatter handle for the created plot object.",
+        "3-D scatter plots work naturally with `view` and `zlabel`, and all camera state remains subplot-local.",
+        "GPU-resident coordinate buffers can feed the renderer directly on the happy path; otherwise RunMat gathers once before plotting.",
+        "Marker size and display-name style workflows are handled through the shared plotting object/property system."
+    ],
+    "examples": [
+        {
+            "description": "Plot a 3-D helix as a point cloud",
+            "input": "t = linspace(0, 6*pi, 300);\nscatter3(cos(t), sin(t), t);"
+        },
+        {
+            "description": "Style a 3-D scatter plot and change the camera view",
+            "input": "t = linspace(0, 4*pi, 200);\nh = scatter3(cos(t), sin(t), t);\nset(h, 'DisplayName', 'helix', 'SizeData', 10);\nview(45, 25);"
+        },
+        {
+            "description": "Use subplot-local camera state with multiple 3-D plots",
+            "input": "subplot(1, 2, 1);\nscatter3(1:10, rand(1,10), rand(1,10));\nview(3);\nsubplot(1, 2, 2);\nscatter3(rand(1,10), rand(1,10), rand(1,10));\nview(2);",
+            "output": "% The two subplots keep independent 3-D view state"
+        }
+    ],
+    "links": [
+        {
+            "label": "plot3",
+            "url": "./plot3"
+        },
+        {
+            "label": "scatter",
+            "url": "./scatter"
+        },
+        {
+            "label": "view",
+            "url": "./view"
+        },
+        {
+            "label": "zlabel",
+            "url": "./zlabel"
+        },
+        {
+            "label": "subplot",
+            "url": "./subplot"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/plotting/ops/scatter3.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/plotting/ops/scatter3.rs"
+    },
+    "gpu_residency": "`scatter3` preserves GPU residency when the plotting path can consume exported coordinate buffers directly. If a direct GPU path is not available for the active combination, RunMat gathers once and renders the same plot semantics on the host path.",
+    "gpu_behavior": [
+        "The preferred path keeps point buffers on the device and emits renderer-ready geometry without a full host round-trip.",
+        "Subplot, view, and object-handle behavior is the same on both the GPU and fallback host paths."
+    ],
+    "key": "scatter3",
+    "slug": "scatter3",
+    "categoryPath": [
+        "plotting"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=scatter3.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"scatter3.js","sourceRoot":"","sources":["../../../src/generated/builtins/scatter3.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,uBAAuB;AAIvB,MAAM,UAAU,GAAe;IAC7B,OAAO,EAAE,UAAU;IACnB,UAAU,EAAE,UAAU;IACtB,UAAU,EAAE;QACV,UAAU;QACV,kBAAkB;QAClB,aAAa;QACb,iBAAiB;QACjB,4BAA4B;QAC5B,cAAc;KACf;IACD,SAAS,EAAE,sGAAsG;IACjH,aAAa,EAAE;QACb,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE;YACZ,QAAQ;YACR,QAAQ;SACT;QACD,cAAc,EAAE,MAAM;QACtB,OAAO,EAAE,kIAAkI;KAC5I;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,qCAAqC;QAC7C,aAAa,EAAE,qCAAqC;KACrD;IACD,aAAa,EAAE,mVAAmV;IAClW,WAAW,EAAE;QACX,+EAA+E;QAC/E,mEAAmE;QACnE,wGAAwG;QACxG,kIAAkI;QAClI,8GAA8G;KAC/G;IACD,UAAU,EAAE;QACV;YACE,aAAa,EAAE,mCAAmC;YAClD,OAAO,EAAE,2DAA2D;SACrE;QACD;YACE,aAAa,EAAE,qDAAqD;YACpE,OAAO,EAAE,+HAA+H;SACzI;QACD;YACE,aAAa,EAAE,wDAAwD;YACvE,OAAO,EAAE,kJAAkJ;YAC3J,QAAQ,EAAE,oDAAoD;SAC/D;KACF;IACD,OAAO,EAAE;QACP;YACE,OAAO,EAAE,OAAO;YAChB,KAAK,EAAE,SAAS;SACjB;QACD;YACE,OAAO,EAAE,SAAS;YAClB,KAAK,EAAE,WAAW;SACnB;QACD;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;QACD;YACE,OAAO,EAAE,QAAQ;YACjB,KAAK,EAAE,UAAU;SAClB;QACD;YACE,OAAO,EAAE,SAAS;YAClB,KAAK,EAAE,WAAW;SACnB;KACF;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,+DAA+D;QACxE,KAAK,EAAE,4GAA4G;KACpH;IACD,eAAe,EAAE,yPAAyP;IAC1Q,cAAc,EAAE;QACd,wHAAwH;QACxH,gGAAgG;KACjG;IACD,KAAK,EAAE,UAAU;IACjB,MAAM,EAAE,UAAU;IAClB,cAAc,EAAE;QACd,UAAU;KACX;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

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

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

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

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