bireactive 0.3.0 → 0.3.2

package/dist/core/values/reg/regex.js

@@ -0,0 +1,318 @@
+import { altAll, CharSet as CS, chr, EPS, repeat, seq, seqAll, star, } from "./engine.js";
+/** Thrown when a pattern uses a construct outside the regular subset. */
+export class RegError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "RegError";
+    }
+}
+const LINE_TERMINATORS = CS.of([
+    [0x0a, 0x0a],
+    [0x0d, 0x0d],
+    [0x2028, 0x2029],
+]);
+// JS \s
+const WHITESPACE = CS.of([
+    [0x09, 0x0d],
+    [0x20, 0x20],
+    [0xa0, 0xa0],
+    [0x1680, 0x1680],
+    [0x2000, 0x200a],
+    [0x2028, 0x2029],
+    [0x202f, 0x202f],
+    [0x205f, 0x205f],
+    [0x3000, 0x3000],
+    [0xfeff, 0xfeff],
+]);
+const DIGIT = CS.range(0x30, 0x39);
+const WORD = CS.of([
+    [0x30, 0x39],
+    [0x41, 0x5a],
+    [0x5f, 0x5f],
+    [0x61, 0x7a],
+]);
+/** Compile a `RegExp` to an engine `Re`, or throw `RegError`. */
+export function compileRegex(re) {
+    const flags = { ignoreCase: re.flags.includes("i"), dotAll: re.flags.includes("s") };
+    const p = new Parser(re.source, flags);
+    const r = p.parseAlternation();
+    if (!p.atEnd())
+        throw new RegError(`unexpected "${p.peek()}" at ${p.pos} in /${re.source}/`);
+    return r;
+}
+class Parser {
+    src;
+    flags;
+    pos = 0;
+    constructor(src, flags) {
+        this.src = src;
+        this.flags = flags;
+    }
+    atEnd() {
+        return this.pos >= this.src.length;
+    }
+    peek() {
+        return this.src[this.pos] ?? "";
+    }
+    next() {
+        return this.src[this.pos++] ?? "";
+    }
+    mkChr(set) {
+        return chr(this.flags.ignoreCase ? set.ignoreCase() : set);
+    }
+    parseAlternation() {
+        const branches = [this.parseConcat()];
+        while (this.peek() === "|") {
+            this.next();
+            branches.push(this.parseConcat());
+        }
+        return branches.length === 1 ? branches[0] : altAll(branches);
+    }
+    parseConcat() {
+        const parts = [];
+        while (!this.atEnd() && this.peek() !== "|" && this.peek() !== ")") {
+            parts.push(this.parseQuantified());
+        }
+        return seqAll(parts);
+    }
+    parseQuantified() {
+        const atom = this.parseAtom();
+        return this.applyQuantifier(atom);
+    }
+    applyQuantifier(atom) {
+        const c = this.peek();
+        let out;
+        if (c === "*") {
+            this.next();
+            out = star(atom);
+        }
+        else if (c === "+") {
+            this.next();
+            out = seq(atom, star(atom));
+        }
+        else if (c === "?") {
+            this.next();
+            out = altAll([atom, EPS]);
+        }
+        else if (c === "{") {
+            const saved = this.pos;
+            const bounds = this.tryParseBraces();
+            if (bounds === null) {
+                this.pos = saved;
+                return atom; // a literal "{" — handled as a char by parseAtom next round
+            }
+            out = repeat(atom, bounds[0], bounds[1]);
+        }
+        else {
+            return atom;
+        }
+        if (this.peek() === "?")
+            this.next(); // lazy marker: parsed, ignored
+        return out;
+    }
+    /** Parse `{n}` / `{n,}` / `{n,m}` after the `{`. Returns `null` if it isn't a
+     *  well-formed quantifier (then `{` is a literal). */
+    tryParseBraces() {
+        if (this.peek() !== "{")
+            return null;
+        this.next();
+        const lo = this.readInt();
+        if (lo === null)
+            return null;
+        let hi = lo;
+        if (this.peek() === ",") {
+            this.next();
+            hi = this.peek() === "}" ? undefined : (this.readInt() ?? undefined);
+        }
+        if (this.peek() !== "}")
+            return null;
+        this.next();
+        return [lo, hi];
+    }
+    readInt() {
+        let s = "";
+        while (/[0-9]/.test(this.peek()))
+            s += this.next();
+        return s === "" ? null : Number.parseInt(s, 10);
+    }
+    parseAtom() {
+        const c = this.peek();
+        if (c === "(")
+            return this.parseGroup();
+        if (c === "[")
+            return this.parseClass();
+        if (c === ".") {
+            this.next();
+            return this.mkChr(this.flags.dotAll ? CS.full() : LINE_TERMINATORS.complement());
+        }
+        if (c === "^" || c === "$") {
+            throw new RegError(`anchors (^ $) are not supported: they aren't regular operators`);
+        }
+        if (c === "\\")
+            return this.parseEscape(false);
+        if (c === "*" || c === "+" || c === "?") {
+            throw new RegError(`nothing to repeat before "${c}" at ${this.pos}`);
+        }
+        this.next();
+        return this.mkChr(CS.char(c.charCodeAt(0)));
+    }
+    parseGroup() {
+        this.next(); // (
+        if (this.peek() === "?") {
+            this.next();
+            const k = this.peek();
+            if (k === ":") {
+                this.next();
+            }
+            else if (k === "<" && (this.src[this.pos + 1] === "=" || this.src[this.pos + 1] === "!")) {
+                throw new RegError("lookbehind (?<=…)/(?<!…) is not supported");
+            }
+            else if (k === "<") {
+                // named capture (?<name>…): grouping only, name is irrelevant here
+                this.next();
+                while (!this.atEnd() && this.peek() !== ">")
+                    this.next();
+                if (this.peek() !== ">")
+                    throw new RegError("malformed named group");
+                this.next();
+            }
+            else if (k === "=" || k === "!") {
+                throw new RegError("lookahead (?=…)/(?!…) is not supported");
+            }
+            else {
+                throw new RegError(`unsupported group "(?${k}" at ${this.pos}`);
+            }
+        }
+        const inner = this.parseAlternation();
+        if (this.peek() !== ")")
+            throw new RegError(`unbalanced "(" — expected ")" at ${this.pos}`);
+        this.next();
+        return inner;
+    }
+    parseClass() {
+        this.next(); // [
+        let negated = false;
+        if (this.peek() === "^") {
+            this.next();
+            negated = true;
+        }
+        let set = CS.empty();
+        const add = (s) => {
+            set = set.union(s);
+        };
+        while (!this.atEnd() && this.peek() !== "]") {
+            // a class member: either an escape, or a char, possibly a range a-b
+            let lo;
+            if (this.peek() === "\\") {
+                const e = this.parseEscape(true);
+                lo = e; // either a single-char CharSet or a class-escape CharSet
+            }
+            else {
+                lo = this.next().charCodeAt(0);
+            }
+            if (typeof lo !== "number") {
+                add(lo); // class escape (\d etc.) — can't be a range endpoint
+                continue;
+            }
+            if (this.peek() === "-" && this.src[this.pos + 1] !== "]" && this.pos + 1 < this.src.length) {
+                this.next(); // -
+                let hi;
+                if (this.peek() === "\\") {
+                    const e = this.parseEscape(true);
+                    if (typeof e !== "number") {
+                        // range with a class escape on the right is invalid; treat literally
+                        add(CS.char(lo));
+                        add(CS.char(0x2d));
+                        add(e);
+                        continue;
+                    }
+                    hi = e;
+                }
+                else {
+                    hi = this.next().charCodeAt(0);
+                }
+                add(CS.range(lo, hi));
+            }
+            else {
+                add(CS.char(lo));
+            }
+        }
+        if (this.peek() !== "]")
+            throw new RegError(`unterminated character class`);
+        this.next();
+        return this.mkChr(negated ? set.complement() : set);
+    }
+    parseEscape(inClass) {
+        this.next(); // backslash
+        const c = this.next();
+        const set = (s) => (inClass ? s : this.mkChr(s));
+        const cp = (code) => inClass ? code : this.mkChr(CS.char(code));
+        switch (c) {
+            case "d":
+                return set(DIGIT);
+            case "D":
+                return set(DIGIT.complement());
+            case "w":
+                return set(WORD);
+            case "W":
+                return set(WORD.complement());
+            case "s":
+                return set(WHITESPACE);
+            case "S":
+                return set(WHITESPACE.complement());
+            case "t":
+                return cp(0x09);
+            case "n":
+                return cp(0x0a);
+            case "r":
+                return cp(0x0d);
+            case "f":
+                return cp(0x0c);
+            case "v":
+                return cp(0x0b);
+            case "0":
+                return cp(0x00);
+            case "b":
+                if (inClass)
+                    return cp(0x08); // backspace inside a class
+                throw new RegError("word boundary \\b is not supported");
+            case "B":
+                throw new RegError("non-word-boundary \\B is not supported");
+            case "x": {
+                const h = this.src.slice(this.pos, this.pos + 2);
+                if (!/^[0-9a-fA-F]{2}$/.test(h))
+                    throw new RegError("malformed \\xHH escape");
+                this.pos += 2;
+                return cp(Number.parseInt(h, 16));
+            }
+            case "u":
+                return cp(this.parseUnicodeEscape());
+            default:
+                if (/[1-9]/.test(c))
+                    throw new RegError(`backreference \\${c} is not supported`);
+                if (c === "k")
+                    throw new RegError("named backreference \\k<…> is not supported");
+                return cp(c.charCodeAt(0)); // escaped literal: \. \\ \( etc.
+        }
+    }
+    parseUnicodeEscape() {
+        if (this.peek() === "{") {
+            this.next();
+            let h = "";
+            while (this.peek() !== "}" && !this.atEnd())
+                h += this.next();
+            if (this.peek() !== "}")
+                throw new RegError("malformed \\u{…} escape");
+            this.next();
+            const v = Number.parseInt(h, 16);
+            if (Number.isNaN(v))
+                throw new RegError("malformed \\u{…} escape");
+            return v;
+        }
+        const h = this.src.slice(this.pos, this.pos + 4);
+        if (!/^[0-9a-fA-F]{4}$/.test(h))
+            throw new RegError("malformed \\uHHHH escape");
+        this.pos += 4;
+        return Number.parseInt(h, 16);
+    }
+}

package/dist/core/values/reg/types.d.ts

@@ -0,0 +1,60 @@
+export type Digit = "𝖣";
+export type Lower = "𝖫";
+export type Upper = "𝖴";
+export type Space = "𝖶";
+export type ClassAtom = Digit | Lower | Upper | Space;
+export type Atom = ClassAtom | (string & {});
+type Digits = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9";
+type Lowers = "a" | "b" | "c" | "d" | "e" | "f" | "g" | "h" | "i" | "j" | "k" | "l" | "m" | "n" | "o" | "p" | "q" | "r" | "s" | "t" | "u" | "v" | "w" | "x" | "y" | "z";
+type Uppers = Uppercase<Lowers>;
+type Spaces = " " | "\t" | "\n" | "\r";
+/** Fold one character to its atom (alphanumerics into a class; symbols stay
+ *  singletons). */
+export type Classify<C extends string> = C extends Digits ? Digit : C extends Lowers ? Lower : C extends Uppers ? Upper : C extends Spaces ? Space : C;
+export type FirstChar<S extends string> = S extends `${infer H}${string}` ? H : never;
+export type LastChar<S extends string> = S extends `${infer H}${infer R}` ? R extends "" ? H : LastChar<R> : never;
+/** A boundary: ∅ (a leaf that only matches ""), ⊤ (unknown — the regex
+ *  escape), a finite union of atoms, or a complement (everything but some
+ *  atoms — e.g. `until(",")` ends on anything-but-comma). */
+export type Bound = {
+    readonly k: "none";
+} | {
+    readonly k: "all";
+} | {
+    readonly k: "set";
+    readonly a: Atom;
+} | {
+    readonly k: "co";
+    readonly a: Atom;
+};
+export type NoneBound = {
+    readonly k: "none";
+};
+export type AnyBound = {
+    readonly k: "all";
+};
+export type SetBound<A extends Atom> = {
+    readonly k: "set";
+    readonly a: A;
+};
+export type CoBound<A extends Atom> = {
+    readonly k: "co";
+    readonly a: A;
+};
+type IsNever<T> = [T] extends [never] ? true : false;
+/** Provably disjoint? Returns `false` whenever overlap can't be ruled out, so
+ *  acceptance is always sound (the runtime check is the complete authority). */
+export type Disjoint<A extends Bound, B extends Bound> = A extends NoneBound ? true : B extends NoneBound ? true : A extends AnyBound ? false : B extends AnyBound ? false : A extends SetBound<infer SA> ? B extends SetBound<infer SB> ? IsNever<SA & SB> : B extends CoBound<infer CB> ? IsNever<Exclude<SA, CB>> : false : A extends CoBound<infer CA> ? B extends SetBound<infer SB> ? IsNever<Exclude<SB, CA>> : false : false;
+/** *Provably* overlapping? The compile-time adjacency guard rejects only when
+ *  this is `true`. An unknown boundary (`all`, from the `copy`/`of` escape
+ *  hatch) returns `false` — the escape hatch opts out of *compile-time*
+ *  checking, never of the complete runtime check. */
+export type Overlaps<A extends Bound, B extends Bound> = A extends NoneBound ? false : B extends NoneBound ? false : A extends AnyBound ? false : B extends AnyBound ? false : A extends SetBound<infer SA> ? B extends SetBound<infer SB> ? IsNever<SA & SB> extends true ? false : true : B extends CoBound<infer CB> ? IsNever<Exclude<SA, CB>> extends true ? false : true : false : A extends CoBound<infer CA> ? B extends SetBound<infer SB> ? IsNever<Exclude<SB, CA>> extends true ? false : true : true : false;
+/** Conservative union (may over-approximate to ⊤, which only makes the
+ *  downstream disjointness test stricter — never unsound). */
+export type Union<A extends Bound, B extends Bound> = A extends NoneBound ? B : B extends NoneBound ? A : A extends SetBound<infer SA> ? B extends SetBound<infer SB> ? SetBound<SA | SB> : AnyBound : AnyBound;
+export type DigitBound = SetBound<Digit>;
+export type LetterBound = SetBound<Lower | Upper>;
+export type WordBound = SetBound<Digit | Lower | Upper | "_">;
+export type LitBound<C extends string> = C extends "" ? NoneBound : SetBound<Classify<C>>;
+export {};

package/dist/core/values/reg/types.js

@@ -0,0 +1,3 @@
+// ── character-class atoms ─────────────────────────────────────────────
+// Disjoint classes plus symbol characters as their own singleton atoms.
+export {};

package/dist/core/values/reg.d.ts

@@ -0,0 +1,250 @@
+import { Cell, type Optic, type Writable } from "../cell.js";
+import { Arr } from "./arr.js";
+import { type Re } from "./reg/engine.js";
+import type { AnyBound, Bound, Classify, CoBound, DigitBound, FirstChar, LastChar, LetterBound, LitBound, NoneBound, Overlaps, Union, WordBound } from "./reg/types.js";
+import { Str } from "./str.js";
+import { type Codec } from "./template.js";
+/** A parsed star: its elements plus the literal separators between them
+ *  (`seps.length === items.length - 1`), kept so `print` round-trips. */
+export interface StarVal<V = RegVal> {
+    readonly items: readonly V[];
+    readonly seps: readonly string[];
+}
+/** A parsed alternation: which branch matched, and that branch's value. */
+export interface AltVal<V = RegVal> {
+    readonly branch: number;
+    readonly val: V;
+}
+/** The abstract value of a `Reg`. Wide by nature — `match`'s static type
+ *  refines it; `bind` gives typed per-capture handles for editing. */
+export type RegVal = string | number | boolean | null | readonly RegVal[] | StarVal | AltVal;
+/** @internal — the grammar AST (also consumed by `reg/nfa.ts`). */
+export type Node = LitNode | CopyNode | OfNode | SeqNode | AltNode | OptNode | StarNode;
+/** @internal */
+export interface LitNode {
+    readonly kind: "lit";
+    readonly text: string;
+}
+/** @internal */
+export interface CopyNode {
+    readonly kind: "copy";
+    readonly re: RegExp;
+    readonly engine: Re;
+    readonly name?: string;
+}
+/** @internal */
+export interface OfNode {
+    readonly kind: "of";
+    readonly re: RegExp;
+    readonly engine: Re;
+    readonly codec: Codec<unknown>;
+    readonly name?: string;
+}
+/** @internal */
+export interface SeqNode {
+    readonly kind: "seq";
+    readonly parts: readonly Node[];
+}
+/** @internal */
+export interface AltNode {
+    readonly kind: "alt";
+    readonly branches: readonly Node[];
+}
+/** @internal */
+export interface OptNode {
+    readonly kind: "opt";
+    readonly part: Node;
+}
+/** @internal */
+export interface StarNode {
+    readonly kind: "star";
+    readonly part: Node;
+    readonly sep?: Node;
+    readonly joiner: string;
+    /** Minimum element count for an *unseparated* star (0 = Kleene, 1 = plus).
+     *  Separated stars are always ≥1 (split semantics). */
+    readonly min: 0 | 1;
+    /** Resourceful alignment: derive a stable identity from an element's string.
+     *  Element handles then follow that identity across reorders. */
+    readonly key?: (item: string) => string;
+    readonly name?: string;
+}
+/** Source span `[start, end)` of a named capture, recovered by `spans`. */
+export type Span = readonly [start: number, end: number];
+declare const SILENT: unique symbol;
+/** The value of a `lit`: dropped from `seq` tuples. */
+export type Silent = {
+    readonly [SILENT]: true;
+};
+type AnyReg = Reg<any, any, any, any>;
+type ValOf<R> = R extends Reg<infer V, any, any, any> ? V : never;
+type NullOf<R> = R extends Reg<any, infer N, any, any> ? N : never;
+type FirstOf<R> = R extends Reg<any, any, infer F, any> ? F : never;
+type LastOf<R> = R extends Reg<any, any, any, infer L> ? L : never;
+type And<A extends boolean, B extends boolean> = A extends true ? B : false;
+type Or<A extends boolean, B extends boolean> = A extends true ? true : B;
+/** A value as it contributes to a `seq` tuple: `lit` drops out; a nested seq
+ *  tuple splices in; everything else is one slot. */
+type AsTuple<V> = [V] extends [Silent] ? [] : V extends readonly unknown[] ? V : [V];
+/** The value of an optional: inner value when present, `null` when absent; a
+ *  silent inner (no value) records presence as `true`. */
+type OptVal<V> = ([V] extends [Silent] ? true : V) | null;
+/** Boundary of `until(c)`: a single-char delimiter excludes exactly one class
+ *  (`CoBound`); a multi-char delimiter excludes several at runtime but the
+ *  single-atom type algebra can't name that, so it degrades to `AnyBound`
+ *  (sound: defers the adjacency check to construction time). */
+type UntilBound<C extends string> = C extends `${infer _H}${infer R}` ? R extends "" ? CoBound<Classify<C>> : AnyBound : AnyBound;
+/** The brand a bad adjacency degrades the argument list to, so the call site
+ *  fails with this message. */
+type AdjErr = {
+    readonly __ambiguous: "adjacent parts overlap — insert a lit() delimiter or use disjoint character classes";
+};
+/** Options for `bind` / `view`. */
+export interface BindOpts {
+    strict?: boolean;
+}
+/** A bound named handle: a `string` capture is a `Writable<Str>`; a `star`
+ *  capture is an editable `Arr<string>`. */
+export type Handle = Writable<Str> | Arr<string>;
+/** Schema tag for the typed `bind` overload: `"str"` → scalar, `"arr"` → star. */
+export type HandleKind = "str" | "arr";
+/** The concrete handle type for a schema tag. */
+export type HandleOf<K extends HandleKind> = K extends "arr" ? Arr<string> : Writable<Str>;
+/** An immutable bidirectional string-lens description. Build with the typed
+ *  leaf builders and combinators, then `bind`/`view` onto a `Cell<string>`.
+ *
+ *  The four type parameters are phantom: `V` is the parsed value, `N` whether
+ *  it accepts "", and `F`/`L` the character classes its match can begin/end
+ *  with. `F`/`L`/`N` drive the compile-time ambiguity checks; they have no
+ *  runtime presence. */
+export declare class Reg<V = RegVal, N extends boolean = boolean, F extends Bound = AnyBound, L extends Bound = AnyBound> {
+    #private;
+    /** @internal */
+    readonly root: Node;
+    /** @internal — use the static builders. */
+    constructor(root: Node);
+    /** A fixed delimiter: matched and printed, never surfaced as a value. */
+    static lit<T extends string>(text: T): Reg<Silent, T extends "" ? true : false, LitBound<FirstChar<T>>, LitBound<LastChar<T>>>;
+    /** Text up to (but not including) the delimiter `c` — i.e. `[^c]*`. Nullable
+     *  (an empty field is allowed); the natural companion of `star(lit(c))`. */
+    static until<C extends string>(c: C): Reg<string, true, UntilBound<C>, UntilBound<C>>;
+    /** One or more digits, `\d+`, as a string. */
+    static digits(): Reg<string, false, DigitBound, DigitBound>;
+    /** One or more digits, decoded as a `number` (a quotient lens — leading
+     *  zeros are not preserved). */
+    static int(): Reg<number, false, DigitBound, DigitBound>;
+    /** One or more ASCII letters, `[A-Za-z]+`. */
+    static letters(): Reg<string, false, LetterBound, LetterBound>;
+    /** One or more word characters, `\w+` (letters, digits, underscore). */
+    static word(): Reg<string, false, WordBound, WordBound>;
+    /** The escape hatch: capture the text matched by an arbitrary regular `re`.
+     *  Non-regular constructs (anchors, lookaround, backreferences) throw. The
+     *  boundary is opaque to the type system (`AnyBound`), so adjacency can't be
+     *  checked at compile time — the construction-time check still applies. */
+    static copy(re: RegExp): Reg<string, boolean, AnyBound, AnyBound>;
+    /** Typed escape hatch: `re` recognizes, `codec` decodes/encodes. */
+    static of<T>(re: RegExp, codec: Codec<T>): Reg<T, boolean, AnyBound, AnyBound>;
+    /** Unambiguous concatenation; every boundary is checked here and throws on
+     *  ambiguity. (For compile-time adjacency checking, prefer the fluent
+     *  `a.then(b).then(c)`, which validates each link.) */
+    static seq<T extends readonly AnyReg[]>(...parts: T): Reg<SeqVal<T>, SeqNull<T>, SeqFirst<T>, SeqLast<T>>;
+    /** Ordered union; branches must be first-disjoint (checked). */
+    static alt<T extends readonly AnyReg[]>(...branches: T): Reg<AltOf<T>, AltNull<T>, AltFirst<T>, AltLast<T>>;
+    /** Optional (`part` or nothing). `part` must be non-nullable. The value is
+     *  the inner value when present and `null` when absent; an optional with no
+     *  value of its own (e.g. `lit(...).optional()`) records presence as `true`. */
+    static opt<V2, F2 extends Bound, L2 extends Bound>(part: Reg<V2, false, F2, L2>): Reg<OptVal<V2>, true, F2, L2>;
+    /** `seq(this, ...next)`. A provably-overlapping boundary between `this` and
+     *  the next part is a *type* error — so `a.then(b).then(c)` statically checks
+     *  every link. Interior boundaries of a multi-arg call, and the `copy`/`of`
+     *  escapes, are checked at construction (throws). */
+    then<T extends readonly AnyReg[]>(this: Reg<V, N, F, L>, ...next: T extends readonly [infer H extends AnyReg, ...AnyReg[]] ? Overlaps<L, FirstOf<H>> extends true ? readonly AdjErr[] : T : T): Reg<SeqVal<[Reg<V, N, F, L>, ...T]>, SeqNull<[Reg<V, N, F, L>, ...T]>, SeqFirst<[Reg<V, N, F, L>, ...T]>, SeqLast<[Reg<V, N, F, L>, ...T]>>;
+    /** `alt(this, other)`. */
+    or<V2, N2 extends boolean, F2 extends Bound, L2 extends Bound>(this: Reg<V, N, F, L>, other: Reg<V2, N2, F2, L2>): Reg<AltVal<V> | AltValB<V2>, Or<N, N2>, Union<F, F2>, Union<L, L2>>;
+    /** `opt(this)`. Only available when `this` is non-nullable. */
+    optional(this: Reg<V, false, F, L>): Reg<OptVal<V>, true, F, L>;
+    /** Iterate zero-or-more, optionally separated by `sep`; binds to an `Arr`.
+     *  A separated star is a *split* (≥1 piece, like `Str.split`). Pass
+     *  `opts.key` for resourceful alignment across reorders. */
+    star<Vs = never, Ns extends boolean = boolean, Fs extends Bound = Bound, Ls extends Bound = Bound>(this: Reg<V, N, F, L>, sep?: Reg<Vs, Ns, Fs, Ls>, opts?: {
+        key?: (item: string) => string;
+    }): Reg<StarVal<V>, true, F, L>;
+    /** Iterate one-or-more (forbids the empty list when unseparated). */
+    plus<Vs = never, Ns extends boolean = boolean, Fs extends Bound = Bound, Ls extends Bound = Bound>(this: Reg<V, N, F, L>, sep?: Reg<Vs, Ns, Fs, Ls>, opts?: {
+        key?: (item: string) => string;
+    }): Reg<StarVal<V>, N, F, L>;
+    /** Name this capture so `bind` exposes it as a handle (`copy`/`of`/`star`). */
+    as(name: string): Reg<V, N, F, L>;
+    /** Attach a codec to a `copy` leaf, turning it into a typed `of` capture. */
+    map<T>(codec: Codec<T>): Reg<T, N, F, L>;
+    /** Parse `s` fully (must consume to the end); `null` if it doesn't match.
+     *  Single-pass and linear. */
+    match(s: string): V | null;
+    /** Reflective print: render a value back to source text. */
+    print(v: V): string;
+    /** Does `s` fully match? Linear. */
+    test(s: string): boolean;
+    /** Source spans of each named capture, keyed by name — the `get`/`put`
+     *  correspondence made visible. Empty if `s` doesn't fully match. */
+    spans(s: string): Record<string, Span>;
+    /** This grammar as a first-class, composable `Optic<string, V>`: `get`
+     *  parses (falling back to the default value off-language), `put` reprints
+     *  and round-trip-guards (an off-language source or a non-round-tripping
+     *  value leaves the source untouched). Drops straight into `compose(...)`
+     *  and `cell.through(...)`, so it chains with `atKey`/`iso` and string
+     *  lenses like `caseFold`. */
+    optic(): Optic<string, V>;
+    /** The whole abstract value as a writable lens over `source`. */
+    view(source: Cell<string>): Writable<Cell<V>>;
+    /** Bind named captures (`.as`) to editable handles over `source`: a string
+     *  capture → `Writable<Str>`, a `star` capture → `Arr<string>`.
+     *
+     *  Pass `opts.schema` (`{ name: "str" | "arr" }`) for known keys and
+     *  per-handle types without casts. */
+    bind<S extends Record<string, HandleKind>>(source: Cell<string>, opts: {
+        schema: S;
+    }): {
+        [K in keyof S]: HandleOf<S[K]>;
+    };
+    bind(source: Cell<string>, opts?: BindOpts): Record<string, Handle>;
+}
+type SeqVal<T extends readonly AnyReg[]> = T extends readonly [
+    infer H extends AnyReg,
+    ...infer R extends readonly AnyReg[]
+] ? [...AsTuple<ValOf<H>>, ...SeqVal<R>] : [];
+type SeqNull<T extends readonly AnyReg[]> = T extends readonly [
+    infer H extends AnyReg,
+    ...infer R extends readonly AnyReg[]
+] ? And<NullOf<H>, SeqNull<R>> : true;
+type SeqFirst<T extends readonly AnyReg[]> = T extends readonly [
+    infer H extends AnyReg,
+    ...infer R extends readonly AnyReg[]
+] ? NullOf<H> extends true ? Union<FirstOf<H>, SeqFirst<R>> : FirstOf<H> : NoneBound;
+type SeqLast<T extends readonly AnyReg[]> = T extends readonly [
+    ...infer R extends readonly AnyReg[],
+    infer Last extends AnyReg
+] ? NullOf<Last> extends true ? Union<LastOf<Last>, SeqLast<R>> : LastOf<Last> : NoneBound;
+type AltOf<T extends readonly AnyReg[]> = T extends readonly [
+    infer H extends AnyReg,
+    ...infer R extends readonly AnyReg[]
+] ? R extends readonly [] ? AltVal<ValOf<H>> : AltVal<ValOf<H>> | AltShift<AltOf<R>> : never;
+type AltShift<U> = U extends AltVal<infer W> ? AltValB<W> : never;
+/** `AltVal` whose branch is ≥1 (used to widen `or`/`alt` unions structurally;
+ *  the runtime tag is the real index). */
+export type AltValB<V> = {
+    readonly branch: number;
+    readonly val: V;
+};
+type AltNull<T extends readonly AnyReg[]> = T extends readonly [
+    infer H extends AnyReg,
+    ...infer R extends readonly AnyReg[]
+] ? Or<NullOf<H>, AltNull<R>> : false;
+type AltFirst<T extends readonly AnyReg[]> = T extends readonly [
+    infer H extends AnyReg,
+    ...infer R extends readonly AnyReg[]
+] ? Union<FirstOf<H>, AltFirst<R>> : NoneBound;
+type AltLast<T extends readonly AnyReg[]> = T extends readonly [
+    infer H extends AnyReg,
+    ...infer R extends readonly AnyReg[]
+] ? Union<LastOf<H>, AltLast<R>> : NoneBound;
+export {};