desmost 0.9.1 → 0.10.0

package/dist/magic/local/line.d.ts

@@ -1,6 +1,6 @@
 import { Incantation, ArgIncantation, type LOCAL } from "../incantation.js";
 import type { DesmostOptions } from "../../options.js";
-import { type Unrecoverable } from "../../errors.js";
+import type { Fallible } from "../../errors.js";
 interface LineOptions {
     style?: keyof typeof Desmos.Styles;
     width?: number;
@@ -12,7 +12,7 @@ export declare class LineIncantation extends ArgIncantation<LOCAL> {
     readonly requires_arg = true;
     readonly arg_type = Incantation.ArgType.OBJECT;
     apply(target: Desmos.ExpressionState, data: LineOptions): void;
-    evaluate_arg(raw: string, options: DesmostOptions): Unrecoverable<LineOptions>;
+    evaluate_arg(raw: string, options: DesmostOptions): Fallible<LineOptions>;
 }
 export {};
 //# sourceMappingURL=line.d.ts.map

package/dist/magic/local/line.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"line.d.ts","sourceRoot":"","sources":["../../../src/magic/local/line.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,KAAK,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAEzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAGlD,UAAU,WAAW;IAEpB,KAAK,CAAC,EAAI,MAAM,OAAO,MAAM,CAAC,MAAM,CAAC;IACrC,KAAK,CAAC,EAAI,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAKD,qBAAa,eAAgB,SAAQ,cAAc,CAAC,KAAK,CAAC;IAEzD,SAAkB,WAAW,8CACgB;IAE7C,SAAkB,UAAU,UAAW;IACvC,SAAkB,YAAY,QAAO;IACrC,SAAkB,QAAQ,8BAAiC;IAElD,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,eAAe,EAAE,IAAI,EAAE,WAAW;IASvD,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,aAAa,CAAC,WAAW,CAAC;CAWvF"}
+{"version":3,"file":"line.d.ts","sourceRoot":"","sources":["../../../src/magic/local/line.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,KAAK,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAEzE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAG7C,UAAU,WAAW;IAEpB,KAAK,CAAC,EAAI,MAAM,OAAO,MAAM,CAAC,MAAM,CAAC;IACrC,KAAK,CAAC,EAAI,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAKD,qBAAa,eAAgB,SAAQ,cAAc,CAAC,KAAK,CAAC;IAEzD,SAAkB,WAAW,8CACgB;IAE7C,SAAkB,UAAU,UAAW;IACvC,SAAkB,YAAY,QAAO;IACrC,SAAkB,QAAQ,8BAAiC;IAElD,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,eAAe,EAAE,IAAI,EAAE,WAAW;IASvD,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,QAAQ,CAAC,WAAW,CAAC;CAWlF"}

package/dist/magic/local/line.js

@@ -1,5 +1,4 @@
 import { Incantation, ArgIncantation } from "../incantation.js";
-import {} from "../../errors.js";
 const VALID_FIELDS = ["style", "width", "opacity"];
 export class LineIncantation extends ArgIncantation {
     description = "Change line styles for a rendered block.";

package/dist/magic/local/line.js.map

@@ -1 +1 @@
-{"version":3,"file":"line.js","sourceRoot":"","sources":["../../../src/magic/local/line.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,cAAc,EAAc,MAAM,gBAAgB,CAAC;AAGzE,OAAO,EAAsB,MAAM,cAAc,CAAC;AAUlD,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;AAGnD,MAAM,OAAO,eAAgB,SAAQ,cAAqB;IAEvC,WAAW,GAC1B,0CAA0C,CAAA;IAE3B,UAAU,GAAK,MAAM,CAAA;IACrB,YAAY,GAAG,IAAI,CAAA;IACnB,QAAQ,GAAO,WAAW,CAAC,OAAO,CAAC,MAAM,CAAA;IAElD,KAAK,CAAC,MAA8B,EAAE,IAAiB;QAE/D,KAAK,CAAC,iBAAiB,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;QAEnD,IAAI,IAAI,CAAC,KAAK,IAAM,SAAS;YAAE,MAAM,CAAC,SAAS,GAAK,IAAI,CAAC,KAAK,CAAC;QAC/D,IAAI,IAAI,CAAC,KAAK,IAAM,SAAS;YAAE,MAAM,CAAC,SAAS,GAAK,IAAI,CAAC,KAAK,CAAC;QAC/D,IAAI,IAAI,CAAC,OAAO,IAAI,SAAS;YAAE,MAAM,CAAC,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC;IAClE,CAAC;IAEQ,YAAY,CAAC,GAAW,EAAE,OAAuB;QAEzD,IAAI,GAAG,GAAG,KAAK,CAAC,YAAY,CAAC,GAAG,EAAE,OAAO,CAAgB,CAAC;QAE1D,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;YACxB,KAAK,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC;YAC5B,KAAK,CAAC,aAAa,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;QACxC,CAAC;QAED,OAAO,GAAG,CAAC;IACZ,CAAC;CACD"}
+{"version":3,"file":"line.js","sourceRoot":"","sources":["../../../src/magic/local/line.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,cAAc,EAAc,MAAM,gBAAgB,CAAC;AAazE,MAAM,YAAY,GAAG,CAAC,OAAO,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;AAGnD,MAAM,OAAO,eAAgB,SAAQ,cAAqB;IAEvC,WAAW,GAC1B,0CAA0C,CAAA;IAE3B,UAAU,GAAK,MAAM,CAAA;IACrB,YAAY,GAAG,IAAI,CAAA;IACnB,QAAQ,GAAO,WAAW,CAAC,OAAO,CAAC,MAAM,CAAA;IAElD,KAAK,CAAC,MAA8B,EAAE,IAAiB;QAE/D,KAAK,CAAC,iBAAiB,CAAC,MAAM,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;QAEnD,IAAI,IAAI,CAAC,KAAK,IAAM,SAAS;YAAE,MAAM,CAAC,SAAS,GAAK,IAAI,CAAC,KAAK,CAAC;QAC/D,IAAI,IAAI,CAAC,KAAK,IAAM,SAAS;YAAE,MAAM,CAAC,SAAS,GAAK,IAAI,CAAC,KAAK,CAAC;QAC/D,IAAI,IAAI,CAAC,OAAO,IAAI,SAAS;YAAE,MAAM,CAAC,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC;IAClE,CAAC;IAEQ,YAAY,CAAC,GAAW,EAAE,OAAuB;QAEzD,IAAI,GAAG,GAAG,KAAK,CAAC,YAAY,CAAC,GAAG,EAAE,OAAO,CAAgB,CAAC;QAE1D,IAAI,OAAO,CAAC,UAAU,EAAE,CAAC;YACxB,KAAK,CAAC,gBAAgB,CAAC,GAAG,CAAC,CAAC;YAC5B,KAAK,CAAC,aAAa,CAAC,GAAG,EAAE,YAAY,CAAC,CAAC;QACxC,CAAC;QAED,OAAO,GAAG,CAAC;IACZ,CAAC;CACD"}

package/dist/options.d.ts

@@ -1,3 +1,9 @@
+/** Default options that Desmost uses for `compile()` and `decompile()`. */
+export declare const DEFAULT_OPTIONS: DesmostOptions;
+/**
+ * Fill in `options` with Desmost's defaults to produce a complete `DesmostOptions` config.
+ */
+export declare function fill_defaults(options: Partial<DesmostOptions> | undefined): DesmostOptions;
 /**
  * Options to customise Desmost compilation.
  *
@@ -24,14 +30,15 @@
  */
 export interface DesmostOptions {
     /**
-     * How should errors be *surfaced* to the end user?
+     * How should errors be displayed?
      *
-     * - `surface` (default): Blocks that result in errors will become Desmos text expressions containing the error message, leaving other expressions unaffected.
+     * - `surface` (default): Blocks that result in errors will become Desmos text blocks containing the error message, leaving other expressions unaffected.
      *
-     * - `crash`: The entire compilation to Desmos will terminate with a single error message. This means you don't get any output at all, but errors are also immediately obvious.
-     *    - Note that this will *clear all expressions* in the calculator instance.
+     * - `crash`: The entire compilation to Desmos will terminate with a single error message in a text block.
+     *   - This means you don't get any Desmos rendering at all, but errors are also immediately obvious.
+     *    - Note that this will *clear all expressions* in the calculator instance. If you pass in a non-blank `Desmos.Calculator` to `compile()`, it could get cleared.
      *
-     * - `suppress`: Silently fail on the frontend (if you wish to give the illusion that everything is fine).
+     * - `suppress`: Silently fail on the frontend (if you wish to give the illusion that everything is fine!).
      */
     errors: "surface" | "crash" | "suppress";
     /**
@@ -45,7 +52,7 @@ export interface DesmostOptions {
     /**
      * The prefix to prepend to error blocks.
      *
-     * Defaults to `[DESMOST ERROR]\n`.
+     * Defaults to `"[DESMOST ERROR]"`.
      *
      * Provide a `""` blank string if you wish for no prefix to be added.
      */
@@ -53,7 +60,7 @@ export interface DesmostOptions {
     /**
      * Show all the available diagnostics for errors, including hints and debug information?
      *
-     * Defaults to `true`, meaning all output is shown.
+     * Defaults to `true` – all output is shown.
      */
     expand_errors: boolean;
     /**
@@ -63,57 +70,84 @@ export interface DesmostOptions {
      *
      * Desmost doesn’t remove unknown fields, it just passes them directly to the Desmos API. If you know what you’re doing and a field you know exists isn’t supported by Desmos, you can disable this to avoid erroring.
      *
-     * Defaults to `true`, meaning arguments are checked. The Desmos API happily accepts and ignores invalid fields, so Desmost provides a safety net for you ;)
+     * Defaults to `true` – arguments are checked. The Desmos API happily accepts and ignores invalid fields, so Desmost provides a safety net for you ;)
      */
     check_args: boolean;
     /**
      * Prettify LaTeX output so it renders nicely in the Desmos editor?
      *
-     * Defaults to `true`, meaning LaTeX is prettified.
+     * This means you can keep your source code much neater. It handles stuff like converting `()` –> `\left(\right)`, `x, y` –> `x,\ y`, `min(x, y)` –> `\operatorname{min}\left(x,\ y\right)`, and more!
+     *
+     * Defaults to `true` – LaTeX is prettified.
      */
     prettify: boolean;
     /**
      * Strip common indentation from `/text{}` blocks?
      *
-     * Defaults to `true`, meaning text is dedented.
+     * This allows you to indent content for readability:
+     *
+     * ```hs
+     * /text{
+     *   Now I have
+     *   a lovely indent
+     * }
+     * ```
+     *
+     * Defaults to `true` – text is dedented.
      */
     dedent_text: boolean;
     /**
-     * Should `%` LaTeX comments be ignored, instead of turned into text expressions (notes)?
+     * Should `%` LaTeX comments be ignored, instead of turned into text blocks (notes)?
      *
-     * Defaults to `false`, meaning comments are kept.
+     * ```hs
+     * % Do I become a text expression?
+     * y = x
+     * ```
+     *
+     * Defaults to `false` – comments are kept.
      */
     ignore_comments: boolean;
     /**
      * Should all line breaks be ignored, instead of kept as blank expressions?
      *
-     * Defaults to `false`, meaning all blank lines are kept.
+     * ```hs
+     * % Should there be a blank block after this?
+     *
+     * % Should there be a blank block before this?
+     * ```
+     *
+     * This takes precedence over `keep_leading_blanks` and `keep_trailing_blanks`.
+     *
+     * Defaults to `false` – blank lines are recognised.
      */
     ignore_all_blanks: boolean;
     /**
      * Should trailing blank lines at the start of the source be kept as blank expressions?
      *
-     * Defaults to `false`, meaning leading blank lines are ignored.
+     * This is disabled by default so line breaks after global incantations don’t mess things up:
+     *
+     * ```hs
+     * /viewport{left: -8, right: 8}
+     *
+     * % I don’t have a blank block above me, yay
+     * ```
+     *
+     * Defaults to `false` – leading blank lines are ignored.
      */
     keep_leading_blanks: boolean;
     /**
      * Should trailing blank lines at the end of the source be kept as blank expressions?
      *
-     * Defaults to `false`, meaning trailing blank lines are ignored.
+     * Defaults to `false` – trailing blank lines are ignored.
      */
     keep_trailing_blanks: boolean;
     /**
-     * Return debug diagnostics?
+     * Return debug diagnostics from `compile()`?
      *
-     * This includes the unevaluated AST and performance diagnostics.
+     * This includes the unevaluated AST and performance diagnostics. Relevant types are exposed from `desmost/internal`, but beware that these are implementation details and unstable.
      *
-     * Defaults to `false`, meaning `compile()` returns `void`.
+     * Defaults to `false` – `compile()` returns `void`.
      */
     debug: boolean;
 }
-export declare const DEFAULT_OPTIONS: DesmostOptions;
-/**
- * Fill in `options` with Desmost's defaults to produce a complete `DesmostOptions` config.
- */
-export declare function fill_defaults(options: Partial<DesmostOptions> | undefined): DesmostOptions;
 //# sourceMappingURL=options.d.ts.map

package/dist/options.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,cAAc;IAE9B;;;;;;;;;OASG;IACH,MAAM,EAAE,SAAS,GAAG,OAAO,GAAG,UAAU,CAAA;IAExC;;;;;;OAMG;IACH,YAAY,EAAE,QAAQ,GAAG,KAAK,GAAG,OAAO,CAAA;IAExC;;;;;;OAMG;IACH,YAAY,EAAE,MAAM,CAAA;IAEpB;;;;OAIG;IACH,aAAa,EAAE,OAAO,CAAA;IAEtB;;;;;;;;OAQG;IACH,UAAU,EAAE,OAAO,CAAA;IAEnB;;;;OAIG;IACH,QAAQ,EAAE,OAAO,CAAA;IAEjB;;;;OAIG;IACH,WAAW,EAAE,OAAO,CAAA;IAEpB;;;;OAIG;IACH,eAAe,EAAE,OAAO,CAAA;IAExB;;;;OAIG;IACH,iBAAiB,EAAE,OAAO,CAAA;IAE1B;;;;OAIG;IACH,mBAAmB,EAAE,OAAO,CAAA;IAE5B;;;;OAIG;IACH,oBAAoB,EAAE,OAAO,CAAA;IAE7B;;;;;;OAMG;IACH,KAAK,EAAE,OAAO,CAAA;CACd;AAGD,eAAO,MAAM,eAAe,EAAE,cAc7B,CAAC;AAGF;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,SAAS,GAAG,cAAc,CAM1F"}
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AAIA,2EAA2E;AAC3E,eAAO,MAAM,eAAe,EAAE,cAc7B,CAAC;AAGF;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,SAAS,GAAG,cAAc,CAM1F;AAGD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,cAAc;IAE9B;;;;;;;;;;OAUG;IACH,MAAM,EAAE,SAAS,GAAG,OAAO,GAAG,UAAU,CAAA;IAExC;;;;;;OAMG;IACH,YAAY,EAAE,QAAQ,GAAG,KAAK,GAAG,OAAO,CAAA;IAExC;;;;;;OAMG;IACH,YAAY,EAAE,MAAM,CAAA;IAEpB;;;;OAIG;IACH,aAAa,EAAE,OAAO,CAAA;IAEtB;;;;;;;;OAQG;IACH,UAAU,EAAE,OAAO,CAAA;IAEnB;;;;;;OAMG;IACH,QAAQ,EAAE,OAAO,CAAA;IAEjB;;;;;;;;;;;;;OAaG;IACH,WAAW,EAAE,OAAO,CAAA;IAEpB;;;;;;;;;OASG;IACH,eAAe,EAAE,OAAO,CAAA;IAExB;;;;;;;;;;;;OAYG;IACH,iBAAiB,EAAE,OAAO,CAAA;IAE1B;;;;;;;;;;;;OAYG;IACH,mBAAmB,EAAE,OAAO,CAAA;IAE5B;;;;OAIG;IACH,oBAAoB,EAAE,OAAO,CAAA;IAE7B;;;;;;OAMG;IACH,KAAK,EAAE,OAAO,CAAA;CACd"}

package/dist/options.js

@@ -1,13 +1,14 @@
 import { LINE } from "./utils.js";
 import { compile } from "./compiler/compile.js";
+/** Default options that Desmost uses for `compile()` and `decompile()`. */
 export const DEFAULT_OPTIONS = {
     errors: "surface",
     place_errors: "inline",
     error_prefix: `[DESMOST ERROR]\n${LINE}\n`,
     expand_errors: true,
+    check_args: true,
     prettify: true,
     dedent_text: true,
-    check_args: false,
     ignore_comments: false,
     ignore_all_blanks: false,
     keep_leading_blanks: false,

package/dist/options.js.map

@@ -1 +1 @@
-{"version":3,"file":"options.js","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAC/B,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAkI7C,MAAM,CAAC,MAAM,eAAe,GAC5B;IACG,MAAM,EAAE,SAAS;IACjB,YAAY,EAAE,QAAQ;IACtB,YAAY,EAAE,oBAAoB,IAAI,IAAI;IAC5C,aAAa,EAAE,IAAI;IACjB,QAAQ,EAAE,IAAI;IAChB,WAAW,EAAE,IAAI;IACjB,UAAU,EAAE,KAAK;IACf,eAAe,EAAE,KAAK;IACtB,iBAAiB,EAAE,KAAK;IACxB,mBAAmB,EAAE,KAAK;IAC1B,oBAAoB,EAAE,KAAK;IAC3B,KAAK,EAAE,KAAK;CACd,CAAC;AAGF;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,OAA4C;IAEvE,OAAO;QACJ,GAAG,eAAe;QAClB,GAAG,OAAO;KACZ,CAAC;AACL,CAAC"}
+{"version":3,"file":"options.js","sourceRoot":"","sources":["../src/options.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAC/B,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAG7C,2EAA2E;AAC3E,MAAM,CAAC,MAAM,eAAe,GAC5B;IACG,MAAM,EAAE,SAAS;IACjB,YAAY,EAAE,QAAQ;IACtB,YAAY,EAAE,oBAAoB,IAAI,IAAI;IAC5C,aAAa,EAAE,IAAI;IACnB,UAAU,EAAE,IAAI;IACd,QAAQ,EAAE,IAAI;IAChB,WAAW,EAAE,IAAI;IACf,eAAe,EAAE,KAAK;IACtB,iBAAiB,EAAE,KAAK;IACxB,mBAAmB,EAAE,KAAK;IAC1B,oBAAoB,EAAE,KAAK;IAC3B,KAAK,EAAE,KAAK;CACd,CAAC;AAGF;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,OAA4C;IAEvE,OAAO;QACJ,GAAG,eAAe;QAClB,GAAG,OAAO;KACZ,CAAC;AACL,CAAC"}

package/dist/parser/ast.d.ts

@@ -1,40 +1,26 @@
-import { UnrecoverableError } from "../errors.js";
 import { Incantation, ArgIncantation } from "../magic/index.js";
 export declare namespace Ast {
     /** What kind of AST node this is. */
     enum Kind {
         EXPRESSION = "Expression",
-        INCANTATION_INVOCATION = "Incantation-Invocation",
-        INVALID_INCANTATION = "Invalid-Incantation"
+        INCANTATION_INVOCATION = "Incantation-Invocation"
     }
     /** A Desmos expression to add to the calculator. */
     interface Expression {
         kind: Kind.EXPRESSION;
         data: Desmos.ExpressionState;
-        incantations: Array<IncantationInvocation<Incantation.Effect.LOCAL> | InvalidInvocation>;
+        incantations: IncantationInvocation<Incantation.Effect.LOCAL>[];
     }
     /** A pending incantation invocation that requires applying its argument (if any), then applying its effect. */
     type IncantationInvocation<Effect extends Incantation.Effect = Incantation.Effect> = {
         kind: Kind.INCANTATION_INVOCATION;
         incantation: Incantation<Effect>;
-        arg_raw: undefined;
     } | {
         kind: Kind.INCANTATION_INVOCATION;
         incantation: ArgIncantation<Effect>;
         arg_raw: string | undefined;
     };
-    /**
-     * An invalid invantation invocation that raised an error when parsed.
-     *
-     * This will be propogated to the user as an extra Desmos text expression (unless they have `errors: "suppress"` configured).
-     */
-    interface InvalidInvocation {
-        kind: Kind.INVALID_INCANTATION;
-        incantation: Incantation;
-        arg_raw?: string;
-        error: UnrecoverableError;
-    }
 }
 /** An abstract object produced by the parser. */
-export type Ast = Ast.Expression | Ast.IncantationInvocation | Ast.InvalidInvocation;
+export type Ast = Ast.Expression | Ast.IncantationInvocation;
 //# sourceMappingURL=ast.d.ts.map

package/dist/parser/ast.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ast.d.ts","sourceRoot":"","sources":["../../src/parser/ast.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAGvD,yBAAiB,GAAG,CACpB;IACC,qCAAqC;IACrC,KAAY,IAAI;QAEf,UAAU,eAA2B;QACrC,sBAAsB,2BAA2B;QACjD,mBAAmB,wBAA2B;KAC9C;IAGD,oDAAoD;IACpD,UAAiB,UAAU;QAE1B,IAAI,EAAE,IAAI,CAAC,UAAU,CAAA;QACrB,IAAI,EAAE,MAAM,CAAC,eAAe,CAAA;QAC5B,YAAY,EAAE,KAAK,CAChB,qBAAqB,CAAC,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,GAC/C,iBAAiB,CAClB,CAAA;KACF;IAGD,+GAA+G;IAC/G,KAAY,qBAAqB,CAAC,MAAM,SAAS,WAAW,CAAC,MAAM,GAAG,WAAW,CAAC,MAAM,IACrF;QACD,IAAI,EAAE,IAAI,CAAC,sBAAsB,CAAA;QACjC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;QAChC,OAAO,EAAE,SAAS,CAAA;KAClB,GACC;QACD,IAAI,EAAE,IAAI,CAAC,sBAAsB,CAAA;QACjC,WAAW,EAAE,cAAc,CAAC,MAAM,CAAC,CAAA;QACnC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;KAC3B,CAAC;IAEH;;;;OAIG;IACH,UAAiB,iBAAiB;QAEjC,IAAI,EAAE,IAAI,CAAC,mBAAmB,CAAA;QAC9B,WAAW,EAAE,WAAW,CAAA;QACxB,OAAO,CAAC,EAAE,MAAM,CAAA;QAChB,KAAK,EAAE,kBAAkB,CAAA;KACzB;CACD;AAED,iDAAiD;AACjD,MAAM,MAAM,GAAG,GACZ,GAAG,CAAC,UAAU,GACd,GAAG,CAAC,qBAAqB,GACzB,GAAG,CAAC,iBAAiB,CACvB"}
+{"version":3,"file":"ast.d.ts","sourceRoot":"","sources":["../../src/parser/ast.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAGvD,yBAAiB,GAAG,CACpB;IACC,qCAAqC;IACrC,KAAY,IAAI;QAEf,UAAU,eAA2B;QACrC,sBAAsB,2BAA2B;KACjD;IAGD,oDAAoD;IACpD,UAAiB,UAAU;QAE1B,IAAI,EAAE,IAAI,CAAC,UAAU,CAAA;QACrB,IAAI,EAAE,MAAM,CAAC,eAAe,CAAA;QAC5B,YAAY,EAAE,qBAAqB,CAAC,WAAW,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAA;KAC/D;IAGD,+GAA+G;IAC/G,KAAY,qBAAqB,CAAC,MAAM,SAAS,WAAW,CAAC,MAAM,GAAG,WAAW,CAAC,MAAM,IACrF;QACD,IAAI,EAAE,IAAI,CAAC,sBAAsB,CAAA;QACjC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;KAChC,GACC;QACD,IAAI,EAAE,IAAI,CAAC,sBAAsB,CAAA;QACjC,WAAW,EAAE,cAAc,CAAC,MAAM,CAAC,CAAA;QACnC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;KAC3B,CAAC;CACH;AAED,iDAAiD;AACjD,MAAM,MAAM,GAAG,GACZ,GAAG,CAAC,UAAU,GACd,GAAG,CAAC,qBAAqB,CAC3B"}

package/dist/parser/ast.js

@@ -1,4 +1,3 @@
-import { UnrecoverableError } from "../errors.js";
 import { Incantation, ArgIncantation } from "../magic/index.js";
 export var Ast;
 (function (Ast) {
@@ -7,7 +6,6 @@ export var Ast;
     (function (Kind) {
         Kind["EXPRESSION"] = "Expression";
         Kind["INCANTATION_INVOCATION"] = "Incantation-Invocation";
-        Kind["INVALID_INCANTATION"] = "Invalid-Incantation";
     })(Kind = Ast.Kind || (Ast.Kind = {}));
 })(Ast || (Ast = {}));
 //# sourceMappingURL=ast.js.map

package/dist/parser/ast.js.map

@@ -1 +1 @@
-{"version":3,"file":"ast.js","sourceRoot":"","sources":["../../src/parser/ast.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAGvD,MAAM,KAAW,GAAG,CAgDnB;AAhDD,WAAiB,GAAG;IAEnB,qCAAqC;IACrC,IAAY,IAKX;IALD,WAAY,IAAI;QAEf,iCAAqC,CAAA;QACrC,yDAAiD,CAAA;QACjD,mDAA8C,CAAA;IAC/C,CAAC,EALW,IAAI,GAAJ,QAAI,KAAJ,QAAI,QAKf;AAwCF,CAAC,EAhDgB,GAAG,KAAH,GAAG,QAgDnB"}
+{"version":3,"file":"ast.js","sourceRoot":"","sources":["../../src/parser/ast.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAGvD,MAAM,KAAW,GAAG,CA8BnB;AA9BD,WAAiB,GAAG;IAEnB,qCAAqC;IACrC,IAAY,IAIX;IAJD,WAAY,IAAI;QAEf,iCAAqC,CAAA;QACrC,yDAAiD,CAAA;IAClD,CAAC,EAJW,IAAI,GAAJ,QAAI,KAAJ,QAAI,QAIf;AAuBF,CAAC,EA9BgB,GAAG,KAAH,GAAG,QA8BnB"}

package/dist/parser/desmost-parser.d.ts

@@ -1,7 +1,8 @@
 import { GenericParser } from "./generic-parser.js";
 import { Ast } from "./ast.js";
 import type { DesmostOptions } from "../options.js";
-import type { NoMatch, Unrecoverable } from "../errors.js";
+import { DesmostError } from "../errors.js";
+import type { NoMatch, Fallible } from "../errors.js";
 import { Incantation } from "../magic/index.js";
 import type { GLOBAL, LOCAL } from "../magic/index.js";
 /**
@@ -11,52 +12,62 @@ export declare class DesmostParser extends GenericParser {
     protected options?: DesmostOptions | undefined;
     constructor(source: string, options?: DesmostOptions | undefined);
     /**
-     * Parse the next semantic block of source code, producing an `Ast` object, or `null` if the parser has successfully reached the end of the source code.
+     * Parse the next semantic block of source code.
+     *
+     * This returns:
+     *
+     * ```ts
+     * // an AST block(s) + any errors encountered
+     * { blocks: Ast[], errors: [...] }
+     *
+     * // ignored block + any errors encountered
+     * { blocks: [], errors: [...] }
+     *
+     * // parser has reached the end of the source
+     * undefined
+     * ```
+     *
+     * `block: null` could be ignored content like comments, or it could be a parse that couldn't recover and so failed to produce a block.
      */
-    parse_next(): Ast | null;
+    parse_next(): Fallible<{
+        blocks: Ast[];
+        errors: DesmostError[];
+    } | undefined>;
     /**
      * Parse Desmost syntax before the `::` separator, which may be:
      *
      * - 1 global incantation
      * - 1+ local incantations
      */
-    parse_pre_sep(): Unrecoverable<{
-        global: Ast.IncantationInvocation<GLOBAL> | Ast.InvalidInvocation;
+    parse_pre_sep(): Fallible<{
+        global: Ast.IncantationInvocation<GLOBAL> | null;
     } | {
-        local: Array<Ast.IncantationInvocation<LOCAL> | Ast.InvalidInvocation>;
+        locals: Ast.IncantationInvocation<LOCAL>[];
     }>;
     /**
      * Parse the Desmost `::` separator.
      */
-    parse_sep(): Unrecoverable<void>;
+    parse_sep(): Fallible<void>;
     /**
      * Parse Desmost syntax after the `::` separator, which may be:
      *
      * - 1 line of LaTeX
      * - 1 expression incantation
      */
-    parse_post_sep(): Unrecoverable<Ast.Expression>;
-    parse_comment(): Unrecoverable<Ast.Expression>;
+    parse_post_sep(): Fallible<Ast.Expression>;
+    parse_comment(): Fallible<Ast.Expression>;
     /**
      * Parse a single line of arbitrary text.
      */
-    parse_line(): Unrecoverable<string>;
-    /**
-     * Attempt to parse a global incantation invocation.
-     */
-    try_parse_global_incantation(): Ast.IncantationInvocation<GLOBAL> | Ast.InvalidInvocation | NoMatch;
+    parse_line(): Fallible<string>;
     /**
-     * Attempt to parse a local incantation invocation.
+     * Attempt to parse an incantation invocation allowed by `incantations`.
      */
-    try_parse_local_incantation(): Ast.IncantationInvocation<LOCAL> | Ast.InvalidInvocation | NoMatch;
+    try_parse_incantation<Effect extends Incantation.Effect>(incantations: Incantation<Effect>[]): Fallible<Ast.IncantationInvocation<Effect> | NoMatch>;
     /**
      * Attempt to parse an expression incantation invocation.
      */
-    try_parse_expr_incantation(): Unrecoverable<Ast.Expression | NoMatch>;
-    /**
-     * Attempt to parse an incantation identifier.
-     */
-    try_parse_identifier<Effect extends Incantation.Effect>(incantations: Incantation<Effect>[]): Incantation<Effect> | NoMatch;
+    try_parse_expr_incantation(): Fallible<Ast.Expression | NoMatch>;
     /**
      * Parse an argument to an incantation, enclosed in `{}`.
      *
@@ -121,6 +132,6 @@ export declare class DesmostParser extends GenericParser {
      * - String / LaTeX: Track only balanced `{}` and escaped `\{\}`.
      * - JavaScript object: The above, plus balanced string quotes.
      */
-    arg_type: Incantation.ArgType): Unrecoverable<string>;
+    arg_type: Incantation.ArgType): Fallible<string>;
 }
 //# sourceMappingURL=desmost-parser.d.ts.map

package/dist/parser/desmost-parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"desmost-parser.d.ts","sourceRoot":"","sources":["../../src/parser/desmost-parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAE5B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAGxD,OAAO,EACN,WAAW,EAEX,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,MAAM,EAAE,KAAK,EAAQ,MAAM,UAAU,CAAC;AAGpD;;GAEG;AACH,qBAAa,aAAc,SAAQ,aAAa;IAEnB,SAAS,CAAC,OAAO,CAAC,EAAE,cAAc;gBAAlD,MAAM,EAAE,MAAM,EAAY,OAAO,CAAC,EAAE,cAAc,YAAA;IAQ9D;;OAEG;IACI,UAAU,IAAI,GAAG,GAAG,IAAI;IAkD/B;;;;;OAKG;IACH,aAAa,IACZ,aAAa,CACX;QAAE,MAAM,EAAE,GAAG,CAAC,qBAAqB,CAAC,MAAM,CAAC,GAAG,GAAG,CAAC,iBAAiB,CAAA;KAAE,GACrE;QAAE,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,qBAAqB,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,iBAAiB,CAAC,CAAA;KAAE,CAC3E;IAyBF;;OAEG;IACH,SAAS,IAAI,aAAa,CAAC,IAAI,CAAC;IAShC;;;;;OAKG;IACH,cAAc,IAAI,aAAa,CAAC,GAAG,CAAC,UAAU,CAAC;IA6B/C,aAAa,IAAI,aAAa,CAAC,GAAG,CAAC,UAAU,CAAC;IAe9C;;OAEG;IACH,UAAU,IAAI,aAAa,CAAC,MAAM,CAAC;IAWnC;;OAEG;IACH,4BAA4B,IACzB,GAAG,CAAC,qBAAqB,CAAC,MAAM,CAAC,GACjC,GAAG,CAAC,iBAAiB,GACrB,OAAO;IAuCV;;OAEG;IACH,2BAA2B,IACxB,GAAG,CAAC,qBAAqB,CAAC,KAAK,CAAC,GAChC,GAAG,CAAC,iBAAiB,GACrB,OAAO;IAuCV;;OAEG;IACH,0BAA0B,IAAI,aAAa,CAAC,GAAG,CAAC,UAAU,GAAG,OAAO,CAAC;IAyBrE;;OAEG;IACH,oBAAoB,CAAC,MAAM,SAAS,WAAW,CAAC,MAAM,EACrD,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,EAAE,GACjC,WAAW,CAAC,MAAM,CAAC,GAAG,OAAO;IAgBhC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsDG;IACH,qBAAqB;IACpB;;;;;;;OAOG;IACH,QAAQ,EAAE,WAAW,CAAC,OAAO,GAC3B,aAAa,CAAC,MAAM,CAAC;CA+FxB"}
+{"version":3,"file":"desmost-parser.d.ts","sourceRoot":"","sources":["../../src/parser/desmost-parser.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,OAAO,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAE5B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAY,YAAY,EAAE,MAAM,WAAW,CAAC;AACnD,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAGnD,OAAO,EACN,WAAW,EAEX,MAAM,UAAU,CAAC;AAClB,OAAO,KAAK,EAAE,MAAM,EAAE,KAAK,EAAQ,MAAM,UAAU,CAAC;AAGpD;;GAEG;AACH,qBAAa,aAAc,SAAQ,aAAa;IAEnB,SAAS,CAAC,OAAO,CAAC,EAAE,cAAc;gBAAlD,MAAM,EAAE,MAAM,EAAY,OAAO,CAAC,EAAE,cAAc,YAAA;IAQ9D;;;;;;;;;;;;;;;;;OAiBG;IACI,UAAU,IAChB,QAAQ,CAAC;QAAE,MAAM,EAAE,GAAG,EAAE,CAAC;QAAC,MAAM,EAAE,YAAY,EAAE,CAAA;KAAE,GAAG,SAAS,CAAC;IAyDhE;;;;;OAKG;IACH,aAAa,IACZ,QAAQ,CACN;QAAE,MAAM,EAAE,GAAG,CAAC,qBAAqB,CAAC,MAAM,CAAC,GAAG,IAAI,CAAA;KAAE,GACpD;QAAE,MAAM,EAAE,GAAG,CAAC,qBAAqB,CAAC,KAAK,CAAC,EAAE,CAAA;KAAE,CAC/C;IAoCF;;OAEG;IACH,SAAS,IAAI,QAAQ,CAAC,IAAI,CAAC;IAoC3B;;;;;OAKG;IACH,cAAc,IAAI,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC;IA6B1C,aAAa,IAAI,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC;IAezC;;OAEG;IACH,UAAU,IAAI,QAAQ,CAAC,MAAM,CAAC;IAW9B;;OAEG;IACH,qBAAqB,CAAC,MAAM,SAAS,WAAW,CAAC,MAAM,EACtD,YAAY,EAAE,WAAW,CAAC,MAAM,CAAC,EAAE,GACjC,QAAQ,CAAC,GAAG,CAAC,qBAAqB,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC;IAuCxD;;OAEG;IACH,0BAA0B,IAAI,QAAQ,CAAC,GAAG,CAAC,UAAU,GAAG,OAAO,CAAC;IA+BhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAsDG;IACH,qBAAqB;IACpB;;;;;;;OAOG;IACH,QAAQ,EAAE,WAAW,CAAC,OAAO,GAC3B,QAAQ,CAAC,MAAM,CAAC;CA2FnB"}