runmat 0.3.6 → 0.4.0

package/dist/generated/builtins/ldivide.js

@@ -0,0 +1,248 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "ldivide",
+    "category": "math/elementwise",
+    "keywords": [
+        "ldivide",
+        "element-wise left division",
+        ".\\",
+        "gpu",
+        "implicit expansion"
+    ],
+    "summary": "Element-wise left division A .\\ B (computes B ./ A) with MATLAB-compatible broadcasting, complex support, and GPU fallbacks.",
+    "references": [
+        "https://www.mathworks.com/help/matlab/ref/ldivide.html"
+    ],
+    "gpu_support": {
+        "elementwise": true,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "matlab",
+        "notes": "Prefers provider elem_div/scalar_div/scalar_rdiv hooks; gathers to host when shapes require implicit expansion or operands are unsupported."
+    },
+    "fusion": {
+        "elementwise": true,
+        "reduction": false,
+        "max_inputs": 2,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::math::elementwise::ldivide::tests::ldivide_scalar_numbers",
+        "integration": "builtins::math::elementwise::ldivide::tests::ldivide_row_column_broadcast",
+        "gpu": "builtins::math::elementwise::ldivide::tests::ldivide_gpu_pair_roundtrip",
+        "wgpu": "builtins::math::elementwise::ldivide::tests::ldivide_wgpu_matches_cpu_elementwise",
+        "like_gpu": "builtins::math::elementwise::ldivide::tests::ldivide_like_gpu_prototype_keeps_residency",
+        "like_host": "builtins::math::elementwise::ldivide::tests::ldivide_like_host_gathers_gpu_value",
+        "like_complex": "builtins::math::elementwise::ldivide::tests::ldivide_like_complex_prototype_yields_complex"
+    },
+    "description": "`ldivide(A, B)` (operator form `A .\\ B`) divides each element of `B` by the corresponding element of `A`, delivering MATLAB-compatible left-division semantics. It is equivalent to `B ./ A` but keeps argument order consistent with MATLAB source code and operator precedence.",
+    "behaviors": [
+        "Supports real, complex, logical, and character inputs; logical and character data are promoted to double precision before division.",
+        "Implicit expansion follows MATLAB rules: singleton dimensions expand automatically, while mismatched non-singleton extents raise MATLAB-compatible size errors.",
+        "Complex operands use the analytic continuation `B ./ A`, propagating `NaN` and `Inf` exactly as MATLAB does.",
+        "Empty shapes propagate cleanly—if the broadcasted output has a zero dimension, the result is empty with the expected shape.",
+        "Integer inputs promote to double precision, mirroring MATLAB’s numeric tower.",
+        "The optional `'like'` prototype makes the result adopt the residency (host or GPU) and numeric flavour of the prototype. Complex prototypes are honoured on the host today; real gpuArray prototypes keep the result on the device."
+    ],
+    "examples": [
+        {
+            "description": "Left-dividing a vector by a scalar",
+            "input": "A = 2;\nB = [4 6 8];\nQ = ldivide(A, B)",
+            "output": "Q = [2 3 4]"
+        },
+        {
+            "description": "Broadcasting between column divisors and row numerators",
+            "input": "A = (1:3)';         % column of divisors\nB = [10 20 40];     % row of numerators\nM = ldivide(A, B);  % implicit expansion",
+            "output": "M =\n   10.0000   20.0000   40.0000\n    5.0000   10.0000   20.0000\n    3.3333    6.6667   13.3333"
+        },
+        {
+            "description": "Element-wise left division of complex values",
+            "input": "A = [1+2i, 3-4i];\nB = [2-1i, -1+1i];\nZ = ldivide(A, B)",
+            "output": "Z =\n   0.0000 - 1.0000i   -0.2800 - 0.0400i"
+        },
+        {
+            "description": "Dividing character codes by a scalar",
+            "input": "A = 'ABC';\nB = 2;\ncodes = ldivide(A, B)",
+            "output": "codes = [0.0308 0.0303 0.0301]"
+        },
+        {
+            "description": "Computing reciprocals with `ldivide`",
+            "input": "A = [1 2 4 8];\nB = 1;\nR = ldivide(A, B);   % equivalent to 1 ./ A",
+            "output": "R = [1 0.5 0.25 0.125]"
+        },
+        {
+            "description": "Keeping results on the GPU with `'like'`",
+            "input": "proto = gpuArray.zeros(1, 1);\nA = gpuArray([2 4 8 16]);\nB = gpuArray([4 8 16 32]);\ndeviceResult = ldivide(A, B, 'like', proto);\nhostCheck = gather(deviceResult)",
+            "output": "deviceResult =\n  1x4 gpuArray\n    2  2  2  2\nhostCheck = [2 2 2 2]"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `ldivide` support MATLAB implicit expansion?",
+            "answer": "Yes. Singleton dimensions expand automatically; otherwise incompatible shapes raise MATLAB-style errors."
+        },
+        {
+            "question": "What numeric type does `ldivide` return?",
+            "answer": "Real inputs return doubles; mixed or complex inputs return complex doubles. Logical and character inputs promote to double before division."
+        },
+        {
+            "question": "How does `ldivide` handle division by zero?",
+            "answer": "`finite ./ 0` yields signed infinities, and `0 ./ 0` becomes `NaN`, matching MATLAB and IEEE-754 behaviour."
+        },
+        {
+            "question": "Can I divide gpuArrays by host scalars?",
+            "answer": "Yes. Numeric scalars stay on device through `scalar_div`/`scalar_rdiv`. Non-numeric host scalars trigger a gather-then-divide fallback."
+        },
+        {
+            "question": "Does `ldivide` preserve gpuArray residency after a fallback?",
+            "answer": "If the runtime gathers to host (for example, due to implicit expansion), the intermediate stays on the host. Later computations may move it back when auto-offload deems it profitable, or you can request GPU residency explicitly with `'like'`."
+        },
+        {
+            "question": "How do I keep the result on the GPU?",
+            "answer": "Provide a real gpuArray prototype: `ldivide(A, B, 'like', gpuArray.zeros(1,1))`. The runtime re-uploads the host result when necessary."
+        },
+        {
+            "question": "How are empty arrays handled?",
+            "answer": "Empty operands propagate cleanly—the output shape is the broadcasted shape, and the data vector is empty."
+        },
+        {
+            "question": "Are integers and logicals supported?",
+            "answer": "Yes. Both promote to double precision before division so you get MATLAB-compatible numeric results (including `Inf` when dividing by zero)."
+        },
+        {
+            "question": "Can I mix real and complex operands?",
+            "answer": "Absolutely. Mixed cases return complex doubles with full MATLAB semantics."
+        }
+    ],
+    "links": [
+        {
+            "label": "times",
+            "url": "./times"
+        },
+        {
+            "label": "rdivide",
+            "url": "./rdivide"
+        },
+        {
+            "label": "mldivide",
+            "url": "./mldivide"
+        },
+        {
+            "label": "gpuArray",
+            "url": "./gpuarray"
+        },
+        {
+            "label": "gather",
+            "url": "./gather"
+        },
+        {
+            "label": "abs",
+            "url": "./abs"
+        },
+        {
+            "label": "angle",
+            "url": "./angle"
+        },
+        {
+            "label": "conj",
+            "url": "./conj"
+        },
+        {
+            "label": "double",
+            "url": "./double"
+        },
+        {
+            "label": "exp",
+            "url": "./exp"
+        },
+        {
+            "label": "expm1",
+            "url": "./expm1"
+        },
+        {
+            "label": "factorial",
+            "url": "./factorial"
+        },
+        {
+            "label": "gamma",
+            "url": "./gamma"
+        },
+        {
+            "label": "hypot",
+            "url": "./hypot"
+        },
+        {
+            "label": "imag",
+            "url": "./imag"
+        },
+        {
+            "label": "log",
+            "url": "./log"
+        },
+        {
+            "label": "log10",
+            "url": "./log10"
+        },
+        {
+            "label": "log1p",
+            "url": "./log1p"
+        },
+        {
+            "label": "log2",
+            "url": "./log2"
+        },
+        {
+            "label": "minus",
+            "url": "./minus"
+        },
+        {
+            "label": "plus",
+            "url": "./plus"
+        },
+        {
+            "label": "pow2",
+            "url": "./pow2"
+        },
+        {
+            "label": "power",
+            "url": "./power"
+        },
+        {
+            "label": "real",
+            "url": "./real"
+        },
+        {
+            "label": "sign",
+            "url": "./sign"
+        },
+        {
+            "label": "single",
+            "url": "./single"
+        },
+        {
+            "label": "sqrt",
+            "url": "./sqrt"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/math/elementwise/ldivide.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/math/elementwise/ldivide.rs"
+    },
+    "gpu_residency": "You usually do not need to call `gpuArray` manually. RunMat’s auto-offload planner keeps tensors on the GPU whenever provider kernels cover the operation. Explicit `gpuArray` / `gather` calls remain available for MATLAB compatibility; when a provider fallback happens, the runtime gathers to host, computes the MATLAB-accurate answer, and reapplies `'like'` residency requests automatically.",
+    "gpu_behavior": [
+        "When a gpuArray provider is active:\n\n1. If both operands are gpuArrays with identical shapes, RunMat calls the provider’s `elem_div` hook with `(B, A)` so the division runs entirely on the GPU. 2. If the divisor `A` is scalar (host or device) and the numerator `B` is a gpuArray, the runtime uses `scalar_div` to evaluate `B ./ a` on device memory. 3. If the numerator `B` is scalar and the divisor `A` is a gpuArray, `scalar_rdiv` performs `b ./ A` without leaving the GPU. 4. When shapes require implicit expansion—or the provider lacks the necessary kernels—RunMat gathers to the host, computes the MATLAB-accurate result, then reapplies `'like'` residency rules (including re-uploading to a gpuArray when requested). 5. The fusion planner treats `ldivide` as a fusible elementwise node, so adjacent elementwise producers and consumers can execute inside a single GPU pipeline or WGSL kernel, minimising redundant host↔device transfers."
+    ],
+    "key": "ldivide",
+    "slug": "ldivide",
+    "categoryPath": [
+        "math",
+        "elementwise"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=ldivide.js.map

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

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

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

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

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

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

package/dist/generated/builtins/le.js

@@ -0,0 +1,153 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "le",
+    "category": "logical/rel",
+    "keywords": [
+        "le",
+        "<=",
+        "less than or equal",
+        "logical comparison",
+        "gpuArray less-equal"
+    ],
+    "summary": "Element-wise less-than-or-equal comparison for scalars, arrays, strings, and gpuArray inputs.",
+    "references": [],
+    "gpu_support": {
+        "elementwise": true,
+        "reduction": false,
+        "precisions": [
+            "f32",
+            "f64"
+        ],
+        "broadcasting": "matlab",
+        "notes": "Uses provider elem_le kernels when available; otherwise inputs gather back to host memory transparently."
+    },
+    "fusion": {
+        "elementwise": true,
+        "reduction": false,
+        "max_inputs": 2,
+        "constants": "inline"
+    },
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::logical::rel::le::tests",
+        "integration": "builtins::logical::rel::le::tests::le_gpu_provider_roundtrip",
+        "gpu": "builtins::logical::rel::le::tests::le_wgpu_matches_host"
+    },
+    "description": "`le(A, B)` (or the infix `A <= B`) performs an element-wise less-than-or-equal comparison. The result is a logical scalar when the broadcasted shape contains one element, or a logical array otherwise.",
+    "behaviors": [
+        "Numeric, logical, and character inputs compare element-wise using MATLAB's implicit expansion rules.",
+        "Character arrays compare by Unicode code point; mixing them with numeric arrays behaves like comparing numeric codes (`'A' <= 65`).",
+        "String scalars and string arrays compare lexically; implicit expansion works across string dimensions.",
+        "Complex inputs are not supported, matching MATLAB's behaviour.",
+        "Mixed numeric/string inputs raise MATLAB-compatible type errors."
+    ],
+    "examples": [
+        {
+            "description": "Check Whether A Scalar Value Meets A Maximum",
+            "input": "flag = le(17, 42)",
+            "output": "flag =\n     1"
+        },
+        {
+            "description": "Create A Mask For Matrix Values Below Or Equal To A Threshold",
+            "input": "M = [1 2 3; 4 5 6];\nmask = le(M, 3)",
+            "output": "mask =\n  2×3 logical array\n     1     1     1\n     0     0     0"
+        },
+        {
+            "description": "Apply Less-Equal With Implicit Expansion",
+            "input": "v = [1 3 5 7];\nmask = le(v, [2 6])",
+            "output": "mask =\n  1×4 logical array\n     1     1     0     0"
+        },
+        {
+            "description": "Compare Character Data To Numeric Codes With Equality Support",
+            "input": "letters = ['A' 'B' 'C'];\nisBeforeOrB = le(letters, 66)",
+            "output": "isBeforeOrB =\n  1×3 logical array\n     1     1     1"
+        },
+        {
+            "description": "Compare String Arrays Lexicographically Allowing Equality",
+            "input": "names = [\"alice\" \"charlie\" \"bob\"];\nearlierOrSame = le(names, \"bob\")",
+            "output": "earlierOrSame =\n  1×3 logical array\n     1     0     1"
+        },
+        {
+            "description": "Run `le` Directly On `gpuArray` Inputs",
+            "input": "G1 = gpuArray([1 4 7]);\nG2 = gpuArray([2 4 8]);\ndeviceResult = le(G1, G2);\nhostResult = gather(deviceResult)",
+            "output": "deviceResult =\n  1×3 gpuArray logical array\n     1     1     1\nhostResult =\n  1×3 logical array\n     1     1     1"
+        }
+    ],
+    "faqs": [
+        {
+            "question": "Does `le` return logical values?",
+            "answer": "Yes. Scalars return `true` or `false`. Arrays return logical arrays, and `gpuArray` inputs return `gpuArray` logical outputs."
+        },
+        {
+            "question": "How are NaN values treated?",
+            "answer": "Any comparison involving `NaN` returns `false`, matching MATLAB behaviour."
+        },
+        {
+            "question": "Can I compare complex numbers with `le`?",
+            "answer": "No. MATLAB does not define relational ordering for complex numbers, so RunMat raises a MATLAB-compatible error when complex inputs are supplied."
+        },
+        {
+            "question": "How are strings compared?",
+            "answer": "String scalars and arrays compare lexicographically using Unicode code points, with full support for implicit expansion against scalar strings."
+        },
+        {
+            "question": "Are character vectors treated as numbers or text?",
+            "answer": "Character arrays participate as numeric code points when compared to numeric inputs, and they are converted to strings when compared against string scalars or arrays."
+        },
+        {
+            "question": "Do I need to gather results manually after a GPU comparison?",
+            "answer": "No. When both inputs are `gpuArray` values and the provider supports `elem_le`, the result stays on the GPU. Otherwise, RunMat gathers inputs transparently and returns a host logical array."
+        },
+        {
+            "question": "Does implicit expansion apply to string arrays?",
+            "answer": "Yes. String arrays support MATLAB-style implicit expansion, so you can compare against scalar strings without manual replication."
+        },
+        {
+            "question": "Can I fuse `le` inside GPU expressions?",
+            "answer": "Yes. The builtin registers element-wise fusion metadata so the planner can fuse comparisons with surrounding GPU-friendly operations."
+        }
+    ],
+    "links": [
+        {
+            "label": "lt",
+            "url": "./lt"
+        },
+        {
+            "label": "eq",
+            "url": "./eq"
+        },
+        {
+            "label": "ne",
+            "url": "./ne"
+        },
+        {
+            "label": "ge",
+            "url": "./ge"
+        },
+        {
+            "label": "gt",
+            "url": "./gt"
+        },
+        {
+            "label": "isequal",
+            "url": "./isequal"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/logical/rel/le.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/logical/rel/le.rs"
+    },
+    "gpu_residency": "You usually do **not** need to call `gpuArray` explicitly. RunMat's native auto-offload planner keeps intermediate results on the GPU when fused expressions benefit from device execution. Explicit `gpuArray` and `gather` calls remain available for compatibility with MATLAB code that manages residency manually.",
+    "gpu_behavior": [
+        "When both operands are `gpuArray` values and the active acceleration provider implements the `elem_le` hook, RunMat executes the comparison entirely on the device and returns a `gpuArray` logical result. If the provider does not expose this hook, the runtime gathers the inputs to host memory automatically and performs the CPU comparison instead of failing."
+    ],
+    "key": "le",
+    "slug": "le",
+    "categoryPath": [
+        "logical",
+        "rel"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=le.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"le.js","sourceRoot":"","sources":["../../../src/generated/builtins/le.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,uBAAuB;AAIvB,MAAM,UAAU,GAAe;IAC7B,OAAO,EAAE,IAAI;IACb,UAAU,EAAE,aAAa;IACzB,UAAU,EAAE;QACV,IAAI;QACJ,IAAI;QACJ,oBAAoB;QACpB,oBAAoB;QACpB,qBAAqB;KACtB;IACD,SAAS,EAAE,+FAA+F;IAC1G,YAAY,EAAE,EAAE;IAChB,aAAa,EAAE;QACb,aAAa,EAAE,IAAI;QACnB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE;YACZ,KAAK;YACL,KAAK;SACN;QACD,cAAc,EAAE,QAAQ;QACxB,OAAO,EAAE,0GAA0G;KACpH;IACD,QAAQ,EAAE;QACR,aAAa,EAAE,IAAI;QACnB,WAAW,EAAE,KAAK;QAClB,YAAY,EAAE,CAAC;QACf,WAAW,EAAE,QAAQ;KACtB;IACD,kBAAkB,EAAE,IAAI;IACxB,QAAQ,EAAE;QACR,MAAM,EAAE,mCAAmC;QAC3C,aAAa,EAAE,8DAA8D;QAC7E,KAAK,EAAE,yDAAyD;KACjE;IACD,aAAa,EAAE,0MAA0M;IACzN,WAAW,EAAE;QACX,sGAAsG;QACtG,qIAAqI;QACrI,wGAAwG;QACxG,gEAAgE;QAChE,kEAAkE;KACnE;IACD,UAAU,EAAE;QACV;YACE,aAAa,EAAE,8CAA8C;YAC7D,OAAO,EAAE,mBAAmB;YAC5B,QAAQ,EAAE,gBAAgB;SAC3B;QACD;YACE,aAAa,EAAE,+DAA+D;YAC9E,OAAO,EAAE,sCAAsC;YAC/C,QAAQ,EAAE,qEAAqE;SAChF;QACD;YACE,aAAa,EAAE,0CAA0C;YACzD,OAAO,EAAE,qCAAqC;YAC9C,QAAQ,EAAE,uDAAuD;SAClE;QACD;YACE,aAAa,EAAE,+DAA+D;YAC9E,OAAO,EAAE,yDAAyD;YAClE,QAAQ,EAAE,wDAAwD;SACnE;QACD;YACE,aAAa,EAAE,2DAA2D;YAC1E,OAAO,EAAE,8EAA8E;YACvF,QAAQ,EAAE,0DAA0D;SACrE;QACD;YACE,aAAa,EAAE,wCAAwC;YACvD,OAAO,EAAE,iHAAiH;YAC1H,QAAQ,EAAE,yHAAyH;SACpI;KACF;IACD,MAAM,EAAE;QACN;YACE,UAAU,EAAE,kCAAkC;YAC9C,QAAQ,EAAE,+HAA+H;SAC1I;QACD;YACE,UAAU,EAAE,6BAA6B;YACzC,QAAQ,EAAE,4EAA4E;SACvF;QACD;YACE,UAAU,EAAE,0CAA0C;YACtD,QAAQ,EAAE,kJAAkJ;SAC7J;QACD;YACE,UAAU,EAAE,2BAA2B;YACvC,QAAQ,EAAE,iJAAiJ;SAC5J;QACD;YACE,UAAU,EAAE,mDAAmD;YAC/D,QAAQ,EAAE,wKAAwK;SACnL;QACD;YACE,UAAU,EAAE,8DAA8D;YAC1E,QAAQ,EAAE,+LAA+L;SAC1M;QACD;YACE,UAAU,EAAE,iDAAiD;YAC7D,QAAQ,EAAE,mIAAmI;SAC9I;QACD;YACE,UAAU,EAAE,yCAAyC;YACrD,QAAQ,EAAE,uIAAuI;SAClJ;KACF;IACD,OAAO,EAAE;QACP;YACE,OAAO,EAAE,IAAI;YACb,KAAK,EAAE,MAAM;SACd;QACD;YACE,OAAO,EAAE,IAAI;YACb,KAAK,EAAE,MAAM;SACd;QACD;YACE,OAAO,EAAE,IAAI;YACb,KAAK,EAAE,MAAM;SACd;QACD;YACE,OAAO,EAAE,IAAI;YACb,KAAK,EAAE,MAAM;SACd;QACD;YACE,OAAO,EAAE,IAAI;YACb,KAAK,EAAE,MAAM;SACd;QACD;YACE,OAAO,EAAE,SAAS;YAClB,KAAK,EAAE,WAAW;SACnB;KACF;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,wDAAwD;QACjE,KAAK,EAAE,qGAAqG;KAC7G;IACD,eAAe,EAAE,yTAAyT;IAC1U,cAAc,EAAE;QACd,wWAAwW;KACzW;IACD,KAAK,EAAE,IAAI;IACX,MAAM,EAAE,IAAI;IACZ,cAAc,EAAE;QACd,SAAS;QACT,KAAK;KACN;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

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

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

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

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

package/dist/generated/builtins/legend.js

@@ -0,0 +1,70 @@
+// @generated by scripts/generate-builtins.cjs
+// Do not edit by hand.
+const builtinDoc = {
+    "title": "legend",
+    "category": "plotting",
+    "keywords": [
+        "legend",
+        "chart legend",
+        "display names",
+        "matlab legend",
+        "series labels"
+    ],
+    "summary": "Show and configure plot legends for labeled series, display names, and MATLAB `legend` workflows.",
+    "requires_feature": null,
+    "tested": {
+        "unit": "builtins::plotting::legend::tests"
+    },
+    "description": "`legend` creates or updates the legend attached to the current axes, or to an explicit axes handle when one is passed. In RunMat, legends are subplot-local and participate in the plotting object system: the builtin returns a legend handle, display names from plotted objects are used automatically, and legend styling can be inspected or updated through `get` and `set`.",
+    "behaviors": [
+        "Calling `legend` with no label arguments uses plotted object display names when they are available.",
+        "Labels can be passed as separate strings, string arrays, or cell arrays, following common MATLAB `legend` workflows.",
+        "Legend visibility and style are axes-local, so enabling or hiding a legend in one subplot does not mutate every axes in the figure.",
+        "The returned handle can be used with `get` and `set` to inspect or update location, orientation, box visibility, font styling, and related legend properties."
+    ],
+    "examples": [
+        {
+            "description": "Build a legend from display names",
+            "input": "x = linspace(0, 2*pi, 200);\nh1 = plot(x, sin(x));\nset(h1, 'DisplayName', 'sin(x)');\nhold on;\nh2 = plot(x, cos(x));\nset(h2, 'DisplayName', 'cos(x)');\nlegend;"
+        },
+        {
+            "description": "Pass labels explicitly and position the legend",
+            "input": "plot(1:5, [1 2 3 4 5]);\nhold on;\nplot(1:5, [5 4 3 2 1]);\nlg = legend('rising', 'falling', 'Location', 'southwest');\nget(lg, 'Type')",
+            "output": "ans =\n    'legend'"
+        },
+        {
+            "description": "Keep legends subplot-local",
+            "input": "subplot(1, 2, 1);\nplot(1:5, 1:5);\nlegend('left');\nsubplot(1, 2, 2);\nplot(1:5, [5 4 3 2 1]);",
+            "output": "% Only the left subplot shows a legend"
+        }
+    ],
+    "links": [
+        {
+            "label": "subplot",
+            "url": "./subplot"
+        },
+        {
+            "label": "get",
+            "url": "./get"
+        },
+        {
+            "label": "set",
+            "url": "./set"
+        },
+        {
+            "label": "plot",
+            "url": "./plot"
+        }
+    ],
+    "source": {
+        "label": "`crates/runmat-runtime/src/builtins/plotting/ops/legend.rs`",
+        "url": "https://github.com/runmat-org/runmat/blob/main/crates/runmat-runtime/src/builtins/plotting/ops/legend.rs"
+    },
+    "key": "legend",
+    "slug": "legend",
+    "categoryPath": [
+        "plotting"
+    ]
+};
+export default builtinDoc;
+//# sourceMappingURL=legend.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"legend.js","sourceRoot":"","sources":["../../../src/generated/builtins/legend.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,uBAAuB;AAIvB,MAAM,UAAU,GAAe;IAC7B,OAAO,EAAE,QAAQ;IACjB,UAAU,EAAE,UAAU;IACtB,UAAU,EAAE;QACV,QAAQ;QACR,cAAc;QACd,eAAe;QACf,eAAe;QACf,eAAe;KAChB;IACD,SAAS,EAAE,mGAAmG;IAC9G,kBAAkB,EAAE,IAAI;IACxB,QAAQ,EAAE;QACR,MAAM,EAAE,mCAAmC;KAC5C;IACD,aAAa,EAAE,oXAAoX;IACnY,WAAW,EAAE;QACX,qGAAqG;QACrG,sHAAsH;QACtH,qIAAqI;QACrI,+JAA+J;KAChK;IACD,UAAU,EAAE;QACV;YACE,aAAa,EAAE,mCAAmC;YAClD,OAAO,EAAE,oKAAoK;SAC9K;QACD;YACE,aAAa,EAAE,gDAAgD;YAC/D,OAAO,EAAE,yIAAyI;YAClJ,QAAQ,EAAE,qBAAqB;SAChC;QACD;YACE,aAAa,EAAE,4BAA4B;YAC3C,OAAO,EAAE,iGAAiG;YAC1G,QAAQ,EAAE,wCAAwC;SACnD;KACF;IACD,OAAO,EAAE;QACP;YACE,OAAO,EAAE,SAAS;YAClB,KAAK,EAAE,WAAW;SACnB;QACD;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,OAAO;SACf;QACD;YACE,OAAO,EAAE,KAAK;YACd,KAAK,EAAE,OAAO;SACf;QACD;YACE,OAAO,EAAE,MAAM;YACf,KAAK,EAAE,QAAQ;SAChB;KACF;IACD,QAAQ,EAAE;QACR,OAAO,EAAE,6DAA6D;QACtE,KAAK,EAAE,0GAA0G;KAClH;IACD,KAAK,EAAE,QAAQ;IACf,MAAM,EAAE,QAAQ;IAChB,cAAc,EAAE;QACd,UAAU;KACX;CACF,CAAC;AAEF,eAAe,UAAU,CAAC"}

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

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

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

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