From c05af65543c78d53f5c6e197b27a5d54ceec6b70 Mon Sep 17 00:00:00 2001
From: Julian Noble <julian@precisium.com.au>
Date: Sat, 18 Jul 2026 18:05:54 +1000
Subject: [PATCH] argparsingtest 1.0.0: per-style parser sets
 opts/tkstyle/tclstyle with N/A capability rows

Restructure of the parser-timing module around three calling styles:
- parser procs move into per-style child namespaces argparsingtest::opts /
  ::tkstyle (2 leading positionals) / ::tclstyle (2 trailing positionals),
  with identical short proc names across styles; the test1_ prefix is gone
- hand-rolled parsers share a manual_ prefix (manual_ni, manual_switch,
  manual_prefix, ...) so they group visually in the comparison tables;
  test1_prefix2 removed (not meaningfully distinct from test1_prefix)
- tkstyle/tclstyle carry a representative roster (manual_switch baseline +
  punkargs/punkargs_by_id/punkargs_parsecache + opt + cmdline + tepam);
  style parsers return a {p1 p2 opts} list
- new 'unsupported' discovery status for library/style combos the backing
  library cannot express: cmdline with leading positionals (getoptions stops
  at the first non-option word - probe verified), argp with any positionals
  (parseArgs walks the whole list as option pairs - source verified).
  compare renders these as N/A rows below the timed rows so every library
  still appears in every style's table
- harness procs (discover_parsers/timeit/first_call/compare) gain
  -style all|opts|tkstyle|tclstyle and return results keyed by style;
  -args requires a single -style (each style has its own default vector);
  external probe keys drop the test1_ prefix (getopt/parse_args/argparse/cmdr)
- punkargs_by_id variants keep the eager punk::args::define as sole doc
  source (the former duplicate argdoc lappend made the lazy namespace scan
  undefine/re-register the id on first introspection); unused struct::set
  require dropped; opt/cmdline/tepam requires hoisted to module top;
  first_call library warm-ups extended with positional coverage
- test suite rewritten: 17 tests including per-parser {p1 p2 opts} contract
  checks across both positional styles, N/A table rendering, roster counts
  and the -style/-args error paths

Assisted-by: harness=claude; primary-model=claude-fable-5; api-location=anthropic.com
---
 src/modules/argparsingtest-999999.0a1.0.tm    | 2283 +++++++++++------
 src/modules/argparsingtest-buildversion.txt   |    6 +-
 .../argparsingtest/argparsingtest.test        |  204 +-
 3 files changed, 1672 insertions(+), 821 deletions(-)

diff --git a/src/modules/argparsingtest-999999.0a1.0.tm b/src/modules/argparsingtest-999999.0a1.0.tm
index 00a7bfc8..db32eaad 100644
--- a/src/modules/argparsingtest-999999.0a1.0.tm
+++ b/src/modules/argparsingtest-999999.0a1.0.tm
@@ -32,6 +32,9 @@
 #*** !doctools
 #[section Overview]
 #[para] overview of argparsingtest
+#[para] Comparative testing of argument parsing implementations across three
+#[para] calling styles: keyed options only, 'tk style' (positionals first) and
+#[para] 'tcl style' (positionals last).
 #[subsection Concepts]
 #[para] -
 
@@ -47,10 +50,15 @@
 
 package require Tcl 8.6-
 package require punk::args
-package require struct::set
+package require opt
+package require cmdline
+package require tepam
 #*** !doctools
 #[item] [package {Tcl 8.6}]
 #[item] [package {punk::args}]
+#[item] [package {opt}]
+#[item] [package {cmdline}]
+#[item] [package {tepam}]
 
 # #package require frobz
 # #*** !doctools
@@ -98,21 +106,872 @@ namespace eval argparsingtest::class {
 # ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
 
 # ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
-# Base namespace
+# Base namespace - timing/comparison harness (the parser implementations under
+# test live in the per-style child namespaces argparsingtest::opts,
+# argparsingtest::tkstyle and argparsingtest::tclstyle further below)
 # ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
 namespace eval argparsingtest {
     namespace export {[a-z]*}  ;# Convention: export all lowercase
-    #variable xyz
 
     #*** !doctools
     #[subsection {Namespace argparsingtest}]
-    #[para] Core API functions for argparsingtest
+    #[para] Core API functions for argparsingtest - parser discovery and timing harness
+    #[list_begin definitions]
+
+    # Parsing-style registry.
+    # Each style holds:
+    #   title  - table section heading used by compare
+    #   argvec - default timing argument vector for the style
+    #   roster - parser proc name -> marker, where marker is one of:
+    #       always      - proc unconditionally defined in argparsingtest::<style>
+    #       argp        - proc defined unconditionally but callable only when the
+    #                     optional argp package loaded at module require time
+    #       unsupported - the backing library cannot express this calling style
+    #                     (no proc exists); reported as unsupported and shown as
+    #                     an N/A row by compare rather than being omitted
+    # Styles:
+    #   opts     - keyed options only
+    #   tkstyle  - 2 mandatory positionals THEN options ('tk style', as in: .c create rect 1 2 3 4 -fill red)
+    #   tclstyle - options THEN 2 mandatory positionals ('tcl style', as in: lsearch -exact $list $val)
+    # The manual_* roster membership differs deliberately: all manual option-loop
+    # variants are compared in the opts style; the positional styles carry a single
+    # manual_switch baseline since the option-loop technique comparison is orthogonal
+    # to positional handling.
+    variable style_info
+    set style_info [dict create {*}{
+        opts {
+            title  "options only"
+            argvec {-return object -x hello -y world -1 1 -2 2 -3 3}
+            roster {
+                manual_ni           always
+                manual_switchmerge  always
+                manual_switch       always
+                manual_switch_nsvar always
+                manual_switch2      always
+                manual_prefix       always
+                punkargs            always
+                punkargs_any        always
+                punkargs_by_id      always
+                punkargs_parsecache always
+                punkargs_validate_ansistripped always
+                opt                 always
+                cmdline_untyped     always
+                cmdline_typed       always
+                argp                argp
+                tepam               always
+            }
+        }
+        tkstyle {
+            title  "tk style (positionals first)"
+            argvec {alpha beta -return object -x hello -y world -1 1 -2 2 -3 3}
+            roster {
+                manual_switch       always
+                punkargs            always
+                punkargs_by_id      always
+                punkargs_parsecache always
+                opt                 always
+                tepam               always
+                cmdline_untyped     unsupported
+                cmdline_typed       unsupported
+                argp                unsupported
+            }
+        }
+        tclstyle {
+            title  "tcl style (positionals last)"
+            argvec {-return object -x hello -y world -1 1 -2 2 -3 3 alpha beta}
+            roster {
+                manual_switch       always
+                punkargs            always
+                punkargs_by_id      always
+                punkargs_parsecache always
+                opt                 always
+                cmdline_untyped     always
+                cmdline_typed       always
+                tepam               always
+                argp                unsupported
+            }
+        }
+    }]
+
+    # Optional external parser packages probed by discover_parsers (parser name -> package name).
+    # No timing wrappers are shipped for these: present -> not_wrappable, absent -> not_loaded.
+    variable optional_externals
+    set optional_externals {
+        getopt      getopt
+        parse_args  parse_args
+        argparse    argparse
+        cmdr        cmdr
+    }
+
+    punk::args::define {
+        @id     -id     ::argparsingtest::discover_parsers
+        @cmd    -name   argparsingtest::discover_parsers\
+            -summary    "Discover available argument parsers per parsing style"\
+            -help\
+                "Returns a dict keyed by style (opts tkstyle tclstyle), each value
+                a dict of parser proc names to their status for that style.
+
+                Statuses:
+                  loaded        - proc callable; timed by default
+                  not_loaded    - backing package absent; proc must not be called
+                  not_wrappable - optional package present but no timing wrapper shipped
+                  unsupported   - backing library cannot express this parsing style
+                                  (shown as an N/A row in compare tables)"
+        @opts   -anyopts 0
+            -style      -default all -type string -choices {all opts tkstyle tclstyle} -help\
+                "Style set(s) to report. Default all reports every style.
+                  The result is keyed by style in all cases."
+    }
+    proc discover_parsers {args} {
+        # discover_parsers - return dict of {style {parser_procname status}}
+        set argd [punk::args::parse $args withid ::argparsingtest::discover_parsers]
+        set style [dict get $argd opts -style]
+        variable style_info
+        variable optional_externals
+        if {$style eq "all"} {
+            set stylelist [dict keys $style_info]
+        } else {
+            set stylelist [list $style]
+        }
+        set result {}
+        foreach s $stylelist {
+            set sresult {}
+            foreach {pname marker} [dict get $style_info $s roster] {
+                switch -- $marker {
+                    always {
+                        dict set sresult $pname loaded
+                    }
+                    argp {
+                        # argp: proc defined unconditionally but registration guarded by catch at
+                        # module load; use package present to check whether the load-time require
+                        # succeeded (no side effects)
+                        if {[catch {package present argp}]} {
+                            dict set sresult $pname not_loaded
+                        } else {
+                            dict set sresult $pname loaded
+                        }
+                    }
+                    unsupported {
+                        dict set sresult $pname unsupported
+                    }
+                }
+            }
+            # Optional externals: probe with package require; no timing wrappers shipped for these
+            foreach {pname pkg} $optional_externals {
+                if {[catch {package require $pkg}]} {
+                    dict set sresult $pname not_loaded
+                } else {
+                    dict set sresult $pname not_wrappable
+                }
+            }
+            dict set result $s $sresult
+        }
+        return $result
+    }
+
+    punk::args::define {
+        @id     -id     ::argparsingtest::timeit
+        @cmd    -name   argparsingtest::timeit\
+            -summary    "Time argument parser performance"\
+            -help\
+                "Runs rough timing comparisons across argument parsers.
+
+                Returns a dict keyed by style, each value mapping parser proc
+                names to timing results. Each timing result is a sub-dict with keys:
+                  us_per_call   - mean microseconds per call
+                  calls_per_sec - mean calls per second
+                  iterations    - iteration count used
+                  warmup        - warmup count used
+                Parsers that error during timing return {error <message>} instead."
+        @opts   -anyopts 0
+            -style      -default all -type string -choices {all opts tkstyle tclstyle} -help\
+                "Style set(s) to time. The result is keyed by style in all cases."
+            -iterations -default 1000 -type integer -help\
+                "Number of timed invocations per parser."
+            -warmup     -default 1    -type integer -help\
+                "Number of untimed warmup invocations before timing starts."
+            -parsers    -default {}   -type list    -help\
+                "List of parser proc names to time. Empty (default) times
+                  all discovered loaded parsers of each selected style."
+            -args       -default {}   -type list    -help\
+                "Argument vector passed to each parser proc during timing.
+                  Empty (default) uses the selected style's default vector.
+                  Only accepted when a single -style is selected."
+    }
+    proc timeit {args} {
+        # timeit - time argument parser performance, returns dict of {style {parser -> timing_info}}
+        set argd [punk::args::parse $args withid ::argparsingtest::timeit]
+        set style      [dict get $argd opts -style]
+        set iterations [dict get $argd opts -iterations]
+        set warmup     [dict get $argd opts -warmup]
+        set parsers    [dict get $argd opts -parsers]
+        set argvec     [dict get $argd opts -args]
+
+        variable style_info
+        if {$style eq "all"} {
+            set stylelist [dict keys $style_info]
+        } else {
+            set stylelist [list $style]
+        }
+        if {[llength $argvec] && [llength $stylelist] > 1} {
+            error "timeit: -args requires a single -style (opts, tkstyle or tclstyle)"
+        }
+
+        set result {}
+        foreach s $stylelist {
+            set sparsers $parsers
+            if {[llength $sparsers] == 0} {
+                set discovered [dict get [discover_parsers -style $s] $s]
+                foreach {pname status} $discovered {
+                    if {$status eq "loaded"} {
+                        lappend sparsers $pname
+                    }
+                }
+            }
+            if {[llength $argvec]} {
+                set svec $argvec
+            } else {
+                set svec [dict get $style_info $s argvec]
+            }
+
+            set sresult {}
+            foreach pname $sparsers {
+                set had_error 0
+                set err_msg {}
+
+                # Use namespace-qualified name (without leading ::) so argp::parseArgs
+                # (which uses info level -1 to identify the caller) can match the
+                # registration stored under argparsingtest::opts::argp. Calling unqualified
+                # breaks argp scoping; calling with leading :: also breaks it because
+                # string map {:: _} adds a spurious leading underscore.
+                set fqname argparsingtest::${s}::$pname
+
+                for {set i 0} {$i < $warmup} {incr i} {
+                    try {
+                        $fqname {*}$svec
+                    } on error {err_result _err_opts} {
+                        set had_error 1
+                        set err_msg $err_result
+                        break
+                    }
+                }
+                if {$had_error} {
+                    dict set sresult $pname [list error $err_msg]
+                    continue
+                }
+
+                set start [clock microseconds]
+                for {set i 0} {$i < $iterations} {incr i} {
+                    try {
+                        $fqname {*}$svec
+                    } on error {err_result _err_opts} {
+                        set had_error 1
+                        set err_msg $err_result
+                        break
+                    }
+                }
+                set end [clock microseconds]
+
+                if {$had_error} {
+                    dict set sresult $pname [list error $err_msg]
+                    continue
+                }
+
+                set us_per_call   [expr {double($end - $start) / $iterations}]
+                set calls_per_sec [expr {1000000.0 / $us_per_call}]
+                set timing {}
+                dict set timing us_per_call   $us_per_call
+                dict set timing calls_per_sec $calls_per_sec
+                dict set timing iterations    $iterations
+                dict set timing warmup        $warmup
+                dict set sresult $pname $timing
+            }
+            dict set result $s $sresult
+        }
+        return $result
+    }
+
+    # Per-library warm-up scripts for first_call's 'warm' timing mode.
+    # Keyed by parser proc name (shared across the style namespaces - the backing
+    # library is the same whatever the calling style); absent key = hand-rolled
+    # parser with no backing library (nothing to pre-compile).
+    # Each script exercises the parser's backing library through sacrificial
+    # definitions/procs so the library's internals are byte-compiled before
+    # the timed first call. The sacrificial definitions cover positional as
+    # well as option handling since the tkstyle/tclstyle sets time positional
+    # parsing. Warm-ups must never touch the definition or registration of the
+    # proc under test - resolving those is legitimately part of that proc's
+    # first-call cost.
+    variable library_warmups
+    set library_warmups [dict create]
+
+    # punk::args-backed parsers share one warm-up covering the withid, withdef
+    # and -cache 1 paths plus the argument types/features the punkargs*
+    # variants use (string/integer/boolean/none types, leaders, values,
+    # -multiple, -choices, -validate_ansistripped).
+    set punkargs_warmup {
+        punk::args::define {
+            @id     -id ::argparsingtest::libwarmup
+            @cmd    -name libwarmup -help "sacrificial definition for punk::args warm-up"
+            @leaders -min 1 -max 1
+            wlead   -type string -optional 0
+            @opts   -anyopts 0
+            -wstr   -default a -type string -choices {a x}
+            -wint   -default 1 -type integer -validate_ansistripped true
+            -wbool  -default 0 -type boolean
+            -wsolo  -type none -multiple 1
+            @values -min 1 -max 1
+            wval    -type string -optional 0
+        }
+        punk::args::parse {L -wstr x -wint 2 -wbool 1 -wsolo V} withid ::argparsingtest::libwarmup
+        punk::args::parse {L -wstr x V} -cache 1 withid ::argparsingtest::libwarmup
+        punk::args::parse {-wstr x} withdef {
+            @id     -id ::argparsingtest::libwarmup_withdef
+            @opts   -anyopts 0
+            -wstr   -default a -type string
+        }
+    }
+    foreach pname {
+        punkargs
+        punkargs_any
+        punkargs_by_id
+        punkargs_parsecache
+        punkargs_validate_ansistripped
+    } {
+        dict set library_warmups $pname $punkargs_warmup
+    }
+    unset pname punkargs_warmup
+
+    dict set library_warmups opt {
+        tcl::OptProc ::argparsingtest::libwarmup_opt {
+            {wpos -string "warm-up positional"}
+            {-w 0 "warm-up option"}
+        } {
+            return [info locals]
+        }
+        ::argparsingtest::libwarmup_opt pval -w 1
+    }
+    dict set library_warmups cmdline_untyped {
+        set libwarmup_args {-w 1}
+        cmdline::getoptions libwarmup_args {
+            {w.arg 0 "warm-up option"}
+        } "usage"
+    }
+    dict set library_warmups cmdline_typed {
+        set libwarmup_args {-w 1}
+        cmdline::typedGetoptions libwarmup_args {
+            {w.integer 0 "warm-up option"}
+        } "usage"
+    }
+    dict set library_warmups tepam {
+        tepam::procedure libwarmup_tepam {
+            -args {
+                {-w -type integer -default 0}
+                {wpos -type string}
+            }
+        } {
+            return [list $w $wpos]
+        }
+        libwarmup_tepam -w 1 pval
+    }
+    # argp caller-key mangling (see the argparsingtest::opts argp registration site):
+    # register inside a namespace and call without a leading '::' so registerArgs'
+    # key matches parseArgs' caller lookup.
+    dict set library_warmups argp {
+        namespace eval ::argparsingtest {
+            argp::registerArgs libwarmup_argp {
+                {-w integer 0}
+            }
+            proc libwarmup_argp {args} {
+                argp::parseArgs opts
+                return [array get opts]
+            }
+        }
+        argparsingtest::libwarmup_argp -w 1
+    }
+
+    punk::args::define {
+        @id     -id     ::argparsingtest::first_call
+        @cmd    -name   argparsingtest::first_call\
+            -summary    "Time cold and warm first-call cost of each argument parser"\
+            -help\
+                "Creates fresh child interpreters for each parser and times
+                the first invocation after loading the argparsingtest module.
+                Child interps load the parent's exact package versions of
+                argparsingtest, punk::args and (when present) punk::lib so the
+                module timed is the one under test rather than any older
+                stable copy visible on the module paths.
+
+                Each parser is timed twice, in separate child interps:
+                  cold - first call immediately after package load. Includes
+                         byte-compilation of the parser proc body and of any
+                         backing-library procs it invokes.
+                  warm - the parser's backing library is first exercised via a
+                         sacrificial definition/proc distinct from the one under
+                         test, so library internals are already byte-compiled
+                         when the timed call runs. This isolates the per-proc
+                         first-use cost (definition resolution, registration
+                         lookup, proc body compile). Hand-rolled parsers have no
+                         backing library to warm; their warm figure is simply a
+                         second cold measurement.
+
+                The timed call uses the selected style's default argument vector.
+
+                Returns a dict keyed by style, each value mapping parser names to
+                a sub-dict with keys cold and warm. Each value is that run's
+                first-call microseconds (float), or {error <message>} if the run
+                fails in the child interp."
+        @opts   -anyopts 0
+            -style      -default all -type string -choices {all opts tkstyle tclstyle} -help\
+                "Style set(s) to time. The result is keyed by style in all cases."
+            -parsers    -default {}   -type list    -help\
+                "List of parser proc names to time. Empty (default) times
+                  all discovered loaded parsers of each selected style."
+    }
+    proc first_call {args} {
+        # first_call - time cold and warm first-call cost of each parser in fresh child interps
+        set argd [punk::args::parse $args withid ::argparsingtest::first_call]
+        set style   [dict get $argd opts -style]
+        set parsers [dict get $argd opts -parsers]
+
+        variable library_warmups
+        variable style_info
+
+        if {$style eq "all"} {
+            set stylelist [dict keys $style_info]
+        } else {
+            set stylelist [list $style]
+        }
+
+        # Capture parent interp's module paths and auto_path for transfer to children
+        set tm_paths [tcl::tm::list]
+        set ap $::auto_path
+
+        # Pin the child's package requires to the versions loaded in the parent.
+        # Plain 'package require' prefers stable versions, so a dev/alpha module
+        # loaded in the parent would otherwise be shadowed in the child by any
+        # older stable copy visible on the module paths - the child would then
+        # time a different module than the one under test. punk::lib is included
+        # (when the parent has it) because it provides the lpop compat shim that
+        # punk::args::parse needs under Tcl 8.6; require order matters - pin
+        # punk::args before punk::lib/argparsingtest so their own plain
+        # 'package require punk::args' calls resolve to the pinned version.
+        set pinned_requires ""
+        foreach pkg {punk::args punk::lib argparsingtest} {
+            if {![catch {package present $pkg} ver]} {
+                append pinned_requires "package require -exact [list $pkg] [list $ver]\n"
+            }
+        }
+
+        set result {}
+        foreach s $stylelist {
+            set svec [dict get $style_info $s argvec]
+            set sparsers $parsers
+            if {[llength $sparsers] == 0} {
+                set discovered [dict get [discover_parsers -style $s] $s]
+                foreach {pname status} $discovered {
+                    if {$status eq "loaded"} {
+                        lappend sparsers $pname
+                    }
+                }
+            }
+
+            set sresult {}
+            foreach pname $sparsers {
+                set timings {}
+                foreach mode {cold warm} {
+                    if {$mode eq "warm" && [dict exists $library_warmups $pname]} {
+                        set warmup [dict get $library_warmups $pname]
+                    } else {
+                        #cold run - or warm run for a parser with no backing library (nothing to pre-compile)
+                        set warmup ""
+                    }
+                    set child [interp create]
+                    try {
+                        # Clear child's tm list and auto_path (which come from the
+                        # environment) then set them to match the parent interp so
+                        # module resolution is identical.
+                        set child_tm [interp eval $child {tcl::tm::list}]
+                        if {[llength $child_tm]} {
+                            interp eval $child [list tcl::tm::path remove {*}$child_tm]
+                        }
+                        interp eval $child [list set ::auto_path $ap]
+                        if {[llength $tm_paths]} {
+                            interp eval $child [list tcl::tm::path add {*}$tm_paths]
+                        }
+
+                        # Load the module (pinned to parent's versions), run any
+                        # library warm-up, then time the FIRST call to this parser.
+                        # Build a script with the requires, warmup, style/pname and
+                        # argvec substituted into place, using expand-style per AGENTS.md.
+                        set script [string cat\
+                            $pinned_requires\
+                            $warmup                                     {*}{
+                            "\nset start \[clock microseconds]\n"
+                        }   "argparsingtest::${s}::$pname $svec\n"      {*}{
+                            "set end \[clock microseconds]\n"
+                            "return \[expr {double(\$end - \$start)}]"
+                        }]
+                        if {[catch {interp eval $child $script} us_val us_opts]} {
+                            dict set timings $mode [list error $us_val]
+                        } else {
+                            dict set timings $mode $us_val
+                        }
+                    } on error {err opts} {
+                        dict set timings $mode [list error $err]
+                    } finally {
+                        interp delete $child
+                    }
+                }
+                dict set sresult $pname $timings
+            }
+            dict set result $s $sresult
+        }
+        return $result
+    }
+
+    punk::args::define {
+        @id     -id     ::argparsingtest::compare
+        @cmd    -name   argparsingtest::compare\
+            -summary    "Compare argument parser performance"\
+            -help\
+                "Runs timing comparisons and outputs results as table, dict, or json.
+
+                Covers one or all parsing styles (see -style). Within each style,
+                rows are sorted fastest-first (ascending us_per_call). Parsers whose
+                backing library cannot express a style are still listed for that
+                style, as N/A rows below the timed rows.
+                - table: per-style human-readable matrix
+                         (first_cold/first_warm columns are first_call timings)
+                - dict:  {results {style {...}} first_call {style {...}}
+                          not_loaded {style {...}} unsupported {style {...}}}
+                         first_call values are {cold <us> warm <us>} sub-dicts (see first_call)
+                - json:  JSON object with results, first_call, not_loaded and
+                         unsupported keys, each keyed by style"
+        @opts   -anyopts 0
+            -style      -default all     -type string  -choices {all opts tkstyle tclstyle} -help\
+                "Style set(s) to compare: all (default) or a single style."
+            -format     -default table   -type string  -choices {table dict json} -help\
+                "Output format: table (default), dict, or json."
+            -iterations -default 1000    -type integer -help\
+                "Number of timed invocations per parser."
+            -warmup     -default 1       -type integer -help\
+                "Number of untimed warmup invocations before timing starts."
+            -parsers    -default {}      -type list    -help\
+                "List of parser proc names to include. Empty (default) covers
+                  each selected style's full roster."
+            -args       -default {}      -type list    -help\
+                "Argument vector passed to each parser proc during timing.
+                  Empty (default) uses the selected style's default vector.
+                  Only accepted when a single -style is selected."
+    }
+    proc compare {args} {
+        # compare - compare argument parser performance, returns formatted table/dict/json
+        set argd [punk::args::parse $args withid ::argparsingtest::compare]
+        set style      [dict get $argd opts -style]
+        set fmt        [dict get $argd opts -format]
+        set iterations [dict get $argd opts -iterations]
+        set warmup     [dict get $argd opts -warmup]
+        set parsers    [dict get $argd opts -parsers]
+        set argvec     [dict get $argd opts -args]
+
+        variable style_info
+        if {$style eq "all"} {
+            set stylelist [dict keys $style_info]
+        } else {
+            set stylelist [list $style]
+        }
+        if {[llength $argvec] && [llength $stylelist] > 1} {
+            error "compare: -args requires a single -style (opts, tkstyle or tclstyle)"
+        }
+
+        set discovered [discover_parsers]
+
+        # Per style: partition the roster (restricted to -parsers when given) into
+        # timing candidates (loaded), N/A rows (unsupported) and the not-loaded
+        # footer list. Requested names unknown to the roster are passed through to
+        # timeit so they surface as error entries rather than vanishing silently.
+        set timeit_dict {}      ;# {style {pname timing}}
+        set first_call_dict {}  ;# {style {pname {cold <us> warm <us>}}}
+        set na_dict {}          ;# {style {pname ...}}   - unsupported for the style
+        set not_loaded_dict {}  ;# {style {pname ...}}   - not_loaded or not_wrappable
+        foreach s $stylelist {
+            set sdisco [dict get $discovered $s]
+            set candidates {}
+            set na {}
+            set notloaded {}
+            if {[llength $parsers]} {
+                set requested $parsers
+            } else {
+                set requested [dict keys $sdisco]
+            }
+            foreach pname $requested {
+                if {![dict exists $sdisco $pname]} {
+                    lappend candidates $pname
+                    continue
+                }
+                switch -- [dict get $sdisco $pname] {
+                    loaded      { lappend candidates $pname }
+                    unsupported { lappend na $pname }
+                    default     { lappend notloaded $pname }
+                }
+            }
+            dict set na_dict $s $na
+            dict set not_loaded_dict $s $notloaded
+
+            if {[llength $candidates]} {
+                set timeit_args [list -style $s -iterations $iterations -warmup $warmup -parsers $candidates]
+                if {[llength $argvec]} {
+                    lappend timeit_args -args $argvec
+                }
+                dict set timeit_dict $s [dict get [timeit {*}$timeit_args] $s]
+                dict set first_call_dict $s [dict get [first_call -style $s -parsers $candidates] $s]
+            } else {
+                dict set timeit_dict $s {}
+                dict set first_call_dict $s {}
+            }
+        }
+
+        switch -- $fmt {
+            table {
+                set style_blocks {}
+                foreach s $stylelist {
+                    set stimeit    [dict get $timeit_dict $s]
+                    set sfc        [dict get $first_call_dict $s]
+                    set sna        [dict get $na_dict $s]
+                    set snotloaded [dict get $not_loaded_dict $s]
+
+                    set colwidth 6
+                    foreach nm [concat [dict keys $stimeit] $sna] {
+                        set l [string length $nm]
+                        if {$l > $colwidth} { set colwidth $l }
+                    }
+                    set rows {}
+                    set error_names {}
+                    foreach {pname timing} $stimeit {
+                        if {[dict exists $timing error]} {
+                            lappend error_names $pname
+                        } else {
+                            set fcold ""
+                            set fwarm ""
+                            if {[dict exists $sfc $pname]} {
+                                set fdict [dict get $sfc $pname]
+                                foreach {mode varname} {cold fcold warm fwarm} {
+                                    if {[dict exists $fdict $mode]} {
+                                        set fval [dict get $fdict $mode]
+                                        if {[llength $fval] == 2 && [lindex $fval 0] eq "error"} {
+                                            set $varname "err"
+                                        } else {
+                                            set $varname [format %.2f $fval]
+                                        }
+                                    }
+                                }
+                            }
+                            lappend rows [list [dict get $timing us_per_call] $pname [dict get $timing calls_per_sec] $fcold $fwarm [dict get $timing iterations]]
+                        }
+                    }
+                    set rows [lsort -real -index 0 $rows]
+                    set lines {}
+                    lappend lines "=== [dict get $style_info $s title] ==="
+                    lappend lines [format "%-${colwidth}s  %12s  %14s  %10s  %10s  %10s" Parser us/call calls/sec first_cold first_warm iterations]
+                    lappend lines [format "%-${colwidth}s  %12s  %14s  %10s  %10s  %10s" [string repeat - $colwidth] [string repeat - 12] [string repeat - 14] [string repeat - 10] [string repeat - 10] [string repeat - 10]]
+                    foreach row $rows {
+                        lassign $row upc pname cps fcold fwarm itr
+                        lappend lines [format "%-${colwidth}s  %12.2f  %14.0f  %10s  %10s  %10d" $pname $upc $cps $fcold $fwarm $itr]
+                    }
+                    foreach pname $sna {
+                        lappend lines [format "%-${colwidth}s  %12s  %14s  %10s  %10s  %10s" $pname N/A N/A N/A N/A N/A]
+                    }
+                    if {[llength $snotloaded] > 0} {
+                        lappend lines "not loaded: [join $snotloaded {, }]"
+                    } else {
+                        lappend lines "not loaded: (none)"
+                    }
+                    if {[llength $error_names] > 0} {
+                        lappend lines "errors: [join $error_names {, }]"
+                    }
+                    lappend style_blocks [join $lines \n]
+                }
+                return [join $style_blocks \n\n]
+            }
+            dict {
+                return [dict create results $timeit_dict first_call $first_call_dict not_loaded $not_loaded_dict unsupported $na_dict]
+            }
+            json {
+                package require json::write
+                set results_pairs {}
+                set fc_pairs {}
+                set nl_pairs {}
+                set na_pairs {}
+                foreach s $stylelist {
+                    set timing_jsons [dict map {k v} [dict get $timeit_dict $s] {
+                        if {[dict exists $v error]} {
+                            json::write object error [json::write string [dict get $v error]]
+                        } else {
+                            set jv_upc [json::write string [dict get $v us_per_call]]
+                            set jv_cps [json::write string [dict get $v calls_per_sec]]
+                            set jv_itr [json::write string [dict get $v iterations]]
+                            set jv_wu  [json::write string [dict get $v warmup]]
+                            json::write object us_per_call $jv_upc calls_per_sec $jv_cps iterations $jv_itr warmup $jv_wu
+                        }
+                    }]
+                    lappend results_pairs $s [json::write object {*}$timing_jsons]
+
+                    set fc_style_pairs {}
+                    foreach {pname fdict} [dict get $first_call_dict $s] {
+                        set mode_pairs {}
+                        foreach mode {cold warm} {
+                            if {[dict exists $fdict $mode]} {
+                                set fval [dict get $fdict $mode]
+                                if {[llength $fval] == 2 && [lindex $fval 0] eq "error"} {
+                                    lappend mode_pairs $mode [json::write object error [json::write string [lindex $fval 1]]]
+                                } else {
+                                    lappend mode_pairs $mode [json::write string $fval]
+                                }
+                            }
+                        }
+                        lappend fc_style_pairs $pname [json::write object {*}$mode_pairs]
+                    }
+                    lappend fc_pairs $s [json::write object {*}$fc_style_pairs]
+
+                    lappend nl_pairs $s [json::write array-strings {*}[dict get $not_loaded_dict $s]]
+                    lappend na_pairs $s [json::write array-strings {*}[dict get $na_dict $s]]
+                }
+                return [json::write object results [json::write object {*}$results_pairs] first_call [json::write object {*}$fc_pairs] not_loaded [json::write object {*}$nl_pairs] unsupported [json::write object {*}$na_pairs]]
+            }
+        }
+    }
+
+    #multiline values use first line of each record to determine amount of indent to trim
+    namespace eval argdoc {
+        lappend PUNKARGS [list {
+            @id     -id     ::argparsingtest::test_multiline
+            @cmd    -name   test_multiline   -summary "multiline default value handling test"   -help "Tests punk::args multiline default indentation using subst."
+            @opts   -anyopts 0
+            -template1  -type string
+            -template2  -type string
+            -template3  -type string
+            -template3b -type string
+            -template4  -type string
+            -template5  -type string
+            -flag       -type boolean   -default 0
+        }]
+    }
+    proc test_multiline {args} {
+        set t3 [textblock::frame t3]
+        set argd [punk::args::parse $args withdef [subst {
+            -template1 -default {
+                ******
+                * t1 *
+                ******
+            }
+                -template2 -default {    ------
+                    ******
+                    * t2 *
+                    ******}
+            -template3 -default {$t3}
+            #substituted or literal values with newlines - no autoindent applied - caller will have to pad appropriately
+            -template3b -default {
+            $t3
+            -----------------
+            $t3
+                   abc\ndef
+            }
+            -template4 -default "******
+            * t4 *
+            ******"
+            -template5 -default "
+
+
+            "
+            -flag -default 0 -type boolean
+        }]]
+        return $argd
+    }
+    namespace eval argdoc {
+        lappend PUNKARGS [list {
+            @id     -id     ::argparsingtest::test_multiline2
+            @cmd    -name   test_multiline2   -summary "multiline default value handling test 2"   -help "Tests punk::args multiline default indentation without subst."
+            @opts   -anyopts 0
+            -template1  -type string
+            -template2  -type string
+            -template3  -type string
+            -template3b -type string
+            -template4  -type string
+            -template5  -type string
+            -flag       -type boolean   -default 0
+        }]
+    }
+    proc test_multiline2 {args} {
+        set t3 [textblock::frame t3]
+        set argd [punk::args::parse $args withdef {
+            -template1 -default {
+                ******
+                * t1 *
+                ******
+            }
+                -template2 -default {    ------
+                    ******
+                    * t2 *
+                    ******}
+            -template3 -default {$t3}
+            #substituted or literal values with newlines - no autoindent applied - caller will have to pad appropriately
+            -template3b -default {
+            ${$t3}
+            -----------------
+            ${$t3}
+                   abc\ndef
+            }
+            -template4 -default "******
+            * t4 *
+            ******"
+            -template5 -default "
+                a
+                    ${$t3}
+                        c
+            "
+            -flag -default 0 -type boolean
+        }]
+        return $argd
+    }
+
+    #proc sample1 {p1 n args} {
+    #    #*** !doctools
+    #    #[call [fun sample1] [arg p1] [arg n] [opt {option value...}]]
+    #    #[para]Description of sample1
+    #    #[para] Arguments:
+    #    #   [list_begin arguments]
+    #    #   [arg_def tring p1]       A description of string argument p1.
+    #    #   [arg_def integer n]      A description of integer argument n.
+    #    #   [list_end]
+    #    return "ok"
+    #}
+
+    #*** !doctools
+    #[list_end] [comment {--- end definitions namespace argparsingtest ---}]
+}
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+
+
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+# Parser implementations - options only
+# All procs accept 10 keyed options and return the parsed options in the
+# parser's natural form (dict for most, array get list for argp).
+# manual_* procs are hand-rolled (no parsing library) and serve as the
+# baseline; the others are named for the library they exercise.
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+namespace eval argparsingtest::opts {
+    namespace export {[a-z]*}  ;# Convention: export all lowercase
+
+    #*** !doctools
+    #[subsection {Namespace argparsingtest::opts}]
+    #[para] parser implementations - keyed options only
     #[list_begin definitions]
 
     namespace eval argdoc {
         lappend PUNKARGS [list {
-            @id     -id     ::argparsingtest::test1_ni
-            @cmd    -name   test1_ni   -summary "dict merge with ni check"   -help "Accepts 10 keyed options. Validates each key using ni (not-in) check; errors on unknown keys."
+            @id     -id     ::argparsingtest::opts::manual_ni
+            @cmd    -name   argparsingtest::opts::manual_ni   -summary "manual parsing - dict merge with ni check"   -help "Accepts 10 keyed options. Validates each key using ni (not-in) check; errors on unknown keys."
             @opts   -anyopts 0
             -return     -default string   -type string
             -frametype  -default \uFFEF   -type string
@@ -126,7 +985,7 @@ namespace eval argparsingtest {
             -3          -default 3        -type integer
         }]
     }
-    proc test1_ni {args} {
+    proc manual_ni {args} {
         set defaults [dict create {*}{
             -return     string
             -frametype  \uFFEF
@@ -148,8 +1007,8 @@ namespace eval argparsingtest {
     }
     namespace eval argdoc {
         lappend PUNKARGS [list {
-            @id     -id     ::argparsingtest::test1_switchmerge
-            @cmd    -name   test1_switchmerge   -summary "switch validation with dict merge"   -help "Accepts 10 keyed options. Validates each key via switch then merges into defaults dict."
+            @id     -id     ::argparsingtest::opts::manual_switchmerge
+            @cmd    -name   argparsingtest::opts::manual_switchmerge   -summary "manual parsing - switch validation with dict merge"   -help "Accepts 10 keyed options. Validates each key via switch then merges into defaults dict."
             @opts   -anyopts 0
             -return     -default string   -type string
             -frametype  -default \uFFEF   -type string
@@ -163,7 +1022,7 @@ namespace eval argparsingtest {
             -3          -default 3        -type integer
         }]
     }
-    proc test1_switchmerge {args} {
+    proc manual_switchmerge {args} {
         set defaults [dict create {*}{
             -return     string
             -frametype  \uFFEF
@@ -189,8 +1048,8 @@ namespace eval argparsingtest {
     #if we need to loop to test arg validity anyway - then dict set as we go is slightly faster than a dict merge at the end
     namespace eval argdoc {
         lappend PUNKARGS [list {
-            @id     -id     ::argparsingtest::test1_switch
-            @cmd    -name   test1_switch   -summary "switch-based arg parsing with dict set"   -help "Accepts 10 keyed options. Uses switch to validate and dict set each value; slightly faster than dict merge."
+            @id     -id     ::argparsingtest::opts::manual_switch
+            @cmd    -name   argparsingtest::opts::manual_switch   -summary "manual parsing - switch with dict set"   -help "Accepts 10 keyed options. Uses switch to validate and dict set each value; slightly faster than dict merge."
             @opts   -anyopts 0
             -return     -default string   -type string
             -frametype  -default \uFFEF   -type string
@@ -204,7 +1063,7 @@ namespace eval argparsingtest {
             -3          -default 3        -type integer
         }]
     }
-    proc test1_switch {args} {
+    proc manual_switch {args} {
         set opts [dict create {*}{
             -return     string
             -frametype  \uFFEF
@@ -245,8 +1104,8 @@ namespace eval argparsingtest {
     #slightly slower than just creating the dict within the proc
     namespace eval argdoc {
         lappend PUNKARGS [list {
-            @id     -id     ::argparsingtest::test1_switch_nsvar
-            @cmd    -name   test1_switch_nsvar   -summary "switch with namespace variable defaults"   -help "Accepts 10 keyed options. Reads defaults from module-level variable switchopts; slightly slower than local dict creation."
+            @id     -id     ::argparsingtest::opts::manual_switch_nsvar
+            @cmd    -name   argparsingtest::opts::manual_switch_nsvar   -summary "manual parsing - switch with namespace variable defaults"   -help "Accepts 10 keyed options. Reads defaults from namespace variable switchopts; slightly slower than local dict creation."
             @opts   -anyopts 0
             -return     -default string   -type string
             -frametype  -default \uFFEF   -type string
@@ -260,7 +1119,7 @@ namespace eval argparsingtest {
             -3          -default 3        -type integer
         }]
     }
-    proc test1_switch_nsvar {args} {
+    proc manual_switch_nsvar {args} {
         variable switchopts
         set opts $switchopts
         foreach {k v} $args {
@@ -277,8 +1136,8 @@ namespace eval argparsingtest {
     }
     namespace eval argdoc {
         lappend PUNKARGS [list {
-            @id     -id     ::argparsingtest::test1_switch2
-            @cmd    -name   test1_switch2   -summary "switch with lmap-built switch arms"   -help "Accepts 10 keyed options. Builds the switch arm list from dict keys via lmap then dispatches with expand."
+            @id     -id     ::argparsingtest::opts::manual_switch2
+            @cmd    -name   argparsingtest::opts::manual_switch2   -summary "manual parsing - switch with lmap-built switch arms"   -help "Accepts 10 keyed options. Builds the switch arm list from dict keys via lmap then dispatches with expand."
             @opts   -anyopts 0
             -return     -default string   -type string
             -frametype  -default \uFFEF   -type string
@@ -292,7 +1151,7 @@ namespace eval argparsingtest {
             -3          -default 3        -type integer
         }]
     }
-    proc test1_switch2 {args} {
+    proc manual_switch2 {args} {
         set opts [dict create {*}{
             -return     string
             -frametype  \uFFEF
@@ -321,43 +1180,8 @@ namespace eval argparsingtest {
     }
     namespace eval argdoc {
         lappend PUNKARGS [list {
-            @id     -id     ::argparsingtest::test1_prefix
-            @cmd    -name   test1_prefix   -summary "prefix-match based arg parsing"   -help "Accepts 10 keyed options. Uses tcl::prefix::match for unique-prefix matching on each call."
-            @opts   -anyopts 0
-            -return     -default string   -type string
-            -frametype  -default \uFFEF   -type string
-            -show_edge  -default \uFFEF   -type string
-            -show_seps  -default \uFFEF   -type string
-            -x          -default ""       -type string
-            -y          -default b        -type string
-            -z          -default c        -type string
-            -1          -default 1        -type boolean
-            -2          -default 2        -type integer
-            -3          -default 3        -type integer
-        }]
-    }
-    proc test1_prefix {args} {
-        set opts [dict create {*}{
-            -return     string
-            -frametype  \uFFEF
-            -show_edge  \uFFEF
-            -show_seps  \uFFEF
-            -x          ""
-            -y          b
-            -z          c
-            -1          1
-            -2          2
-            -3          3
-        }]
-        foreach {k v} $args {
-            dict set opts [tcl::prefix::match -message "test1_prefix option $k" {-return -frametype -show_edge -show_seps -x -y -z -1 -2 -3} $k] $v
-        }
-        return $opts
-    }
-    namespace eval argdoc {
-        lappend PUNKARGS [list {
-            @id     -id     ::argparsingtest::test1_prefix2
-            @cmd    -name   test1_prefix2   -summary "prefix-match with cached knownflags"   -help "Accepts 10 keyed options. Uses tcl::prefix::match with knownflags cached on first non-empty call."
+            @id     -id     ::argparsingtest::opts::manual_prefix
+            @cmd    -name   argparsingtest::opts::manual_prefix   -summary "manual parsing - prefix-match option loop"   -help "Accepts 10 keyed options. Uses tcl::prefix::match for unique-prefix matching on each call."
             @opts   -anyopts 0
             -return     -default string   -type string
             -frametype  -default \uFFEF   -type string
@@ -371,7 +1195,7 @@ namespace eval argparsingtest {
             -3          -default 3        -type integer
         }]
     }
-    proc test1_prefix2 {args} {
+    proc manual_prefix {args} {
         set opts [dict create {*}{
             -return     string
             -frametype  \uFFEF
@@ -384,11 +1208,8 @@ namespace eval argparsingtest {
             -2          2
             -3          3
         }]
-        if {[llength $args]} {
-            set knownflags [dict keys $opts]
-        }
         foreach {k v} $args {
-            dict set opts [tcl::prefix::match -message "test1_prefix2 option $k" $knownflags $k] $v
+            dict set opts [tcl::prefix::match -message "manual_prefix option $k" {-return -frametype -show_edge -show_seps -x -y -z -1 -2 -3} $k] $v
         }
         return $opts
     }
@@ -396,8 +1217,8 @@ namespace eval argparsingtest {
     #punk::args is slower than argp - but comparable, and argp doesn't support solo flags
     namespace eval argdoc {
         lappend PUNKARGS [list {
-            @id     -id     ::argparsingtest::test1_punkargs
-            @cmd    -name   test1_punkargs   -summary "punk::args withdef string types"   -help "Accepts 10 keyed options plus -join. Uses punk::args::parse withdef with string types."
+            @id     -id     ::argparsingtest::opts::punkargs
+            @cmd    -name   argparsingtest::opts::punkargs   -summary "punk::args withdef string types"   -help "Accepts 10 keyed options plus -join. Uses punk::args::parse withdef with string types."
             @opts   -anyopts 0
             -return     -default string   -type string
             -frametype  -default \uFFEF   -type string
@@ -412,10 +1233,10 @@ namespace eval argparsingtest {
             -join       -type none   -multiple 1
         }]
     }
-    proc test1_punkargs {args} {
+    proc punkargs {args} {
         set argd [punk::args::parse $args withdef {
-            @id     -id  ::argparsingtest::test1_punkargs
-            @cmd    -name argtest4 -help "test of punk::args::parse comparative performance"
+            @id     -id  ::argparsingtest::opts::punkargs
+            @cmd    -name argparsingtest::opts::punkargs -help "test of punk::args::parse comparative performance"
             @opts   -anyopts 0
             -return     -default string -type string
             -frametype  -default \uFFEF -type string
@@ -435,8 +1256,8 @@ namespace eval argparsingtest {
 
     namespace eval argdoc {
         lappend PUNKARGS [list {
-            @id     -id     ::argparsingtest::test1_punkargs_any
-            @cmd    -name   test1_punkargs_any   -summary "punk::args withdef any types"   -help "Accepts 10 keyed options plus -join. Uses withdef with -type any for all string-like opts."
+            @id     -id     ::argparsingtest::opts::punkargs_any
+            @cmd    -name   argparsingtest::opts::punkargs_any   -summary "punk::args withdef any types"   -help "Accepts 10 keyed options plus -join. Uses withdef with -type any for all string-like opts."
             @opts   -anyopts 0
             -return     -default string   -type any
             -frametype  -default \uFFEF   -type any
@@ -451,10 +1272,10 @@ namespace eval argparsingtest {
             -join       -type none   -multiple 1
         }]
     }
-    proc test1_punkargs_any {args} {
+    proc punkargs_any {args} {
         set argd [punk::args::parse $args withdef {
-            @id     -id  ::argparsingtest::test1_punkargs
-            @cmd    -name argtest4 -help "test of punk::args::parse comparative performance"
+            @id     -id  ::argparsingtest::opts::punkargs_any
+            @cmd    -name argparsingtest::opts::punkargs_any -help "test of punk::args::parse comparative performance"
             @opts   -anyopts 0
             -return     -default string -type any
             -frametype  -default \uFFEF -type any
@@ -472,9 +1293,17 @@ namespace eval argparsingtest {
         return [tcl::dict::get $argd opts]
     }
 
+    #Sole documentation source is the eager punk::args::define - the load-time
+    #registration is part of what this parser variant measures. No duplicate
+    #argdoc lappend: a second PUNKARGS entry for the same id would make the lazy
+    #namespace scan undefine and re-register the definition on first introspection.
     punk::args::define {
-        @id     -id ::argparsingtest::test1_punkargs_by_id
-        @cmd    -name argtest4 -help "test of punk::args::parse comparative performance"
+        @id     -id ::argparsingtest::opts::punkargs_by_id
+        @cmd    -name argparsingtest::opts::punkargs_by_id\
+            -summary    "punk::args withid pre-registered"\
+            -help\
+                "Accepts 10 keyed options plus -join. Parses via a definition
+                pre-registered at module load, using withid."
         @opts   -anyopts 0
         -return     -default string -type string
         -frametype  -default \uFFEF -type string
@@ -489,33 +1318,15 @@ namespace eval argparsingtest {
         -3          -default 3 -type integer
         @values
     }
-    namespace eval argdoc {
-        lappend PUNKARGS [list {
-            @id     -id     ::argparsingtest::test1_punkargs_by_id
-            @cmd    -name   test1_punkargs_by_id   -summary "punk::args withid pre-registered"   -help "Accepts 10 keyed options plus -join. Parses via a pre-registered definition using withid."
-            @opts   -anyopts 0
-            -return     -default string   -type string
-            -frametype  -default \uFFEF   -type string
-            -show_edge  -default \uFFEF   -type string
-            -show_seps  -default \uFFEF   -type string
-            -x          -default ""       -type string
-            -y          -default b        -type string
-            -z          -default c        -type string
-            -1          -default 1        -type boolean
-            -2          -default 2        -type integer
-            -3          -default 3        -type integer
-            -join       -type none   -multiple 1
-        }]
-    }
-    proc test1_punkargs_by_id {args} {
-        set argd [punk::args::parse $args withid ::argparsingtest::test1_punkargs_by_id]
+    proc punkargs_by_id {args} {
+        set argd [punk::args::parse $args withid ::argparsingtest::opts::punkargs_by_id]
         return [tcl::dict::get $argd opts]
     }
 
     namespace eval argdoc {
         lappend PUNKARGS [list {
-            @id     -id     ::argparsingtest::test1_punkargs_parsecache
-            @cmd    -name   test1_punkargs_parsecache   -summary "punk::args withid with parse cache"   -help "Accepts 10 keyed options plus -join. Uses withid and -cache 1 for repeated parse reuse."
+            @id     -id     ::argparsingtest::opts::punkargs_parsecache
+            @cmd    -name   argparsingtest::opts::punkargs_parsecache   -summary "punk::args withid with parse cache"   -help "Accepts 10 keyed options plus -join. Uses withid and -cache 1 for repeated parse reuse."
             @opts   -anyopts 0
             -return     -default string   -type string
             -frametype  -default \uFFEF   -type string
@@ -530,16 +1341,16 @@ namespace eval argparsingtest {
             -join       -type none   -multiple 1
         }]
     }
-    proc test1_punkargs_parsecache {args} {
-        set argd [punk::args::parse $args -cache 1 withid ::argparsingtest::test1_punkargs_by_id]
+    proc punkargs_parsecache {args} {
+        set argd [punk::args::parse $args -cache 1 withid ::argparsingtest::opts::punkargs_by_id]
         return [tcl::dict::get $argd opts]
     }
 
 
     namespace eval argdoc {
         lappend PUNKARGS [list {
-            @id     -id     ::argparsingtest::test1_punkargs_validate_ansistripped
-            @cmd    -name   test1_punkargs_validate_ansistripped   -summary "punk::args with ansistripped validation"   -help "Accepts 10 keyed options plus -join. Uses withdef and -validate_ansistripped on typed opts."
+            @id     -id     ::argparsingtest::opts::punkargs_validate_ansistripped
+            @cmd    -name   argparsingtest::opts::punkargs_validate_ansistripped   -summary "punk::args with ansistripped validation"   -help "Accepts 10 keyed options plus -join. Uses withdef and -validate_ansistripped on typed opts."
             @opts   -anyopts 0
             -return     -default string   -type string
             -frametype  -default \uFFEF   -type string
@@ -554,10 +1365,10 @@ namespace eval argparsingtest {
             -join       -type none   -multiple 1
         }]
     }
-    proc test1_punkargs_validate_ansistripped {args} {
+    proc punkargs_validate_ansistripped {args} {
         set argd [punk::args::parse $args withdef {
-            @id -id ::argparsingtest::test1_punkargs_validate_ansistripped
-            @cmd -name argtest4 -help "test of punk::args::parse comparative performance"
+            @id -id ::argparsingtest::opts::punkargs_validate_ansistripped
+            @cmd -name argparsingtest::opts::punkargs_validate_ansistripped -help "test of punk::args::parse comparative performance"
             @opts -anyopts 0
             -return     -default string -type string -choices {string object} -help "return type"
             -frametype  -default \uFFEF -type string
@@ -575,12 +1386,10 @@ namespace eval argparsingtest {
         return [tcl::dict::get $argd opts]
     }
 
-    package require opt
-    variable optlist
     namespace eval argdoc {
         lappend PUNKARGS [list {
-            @id     -id     ::argparsingtest::test1_opt
-            @cmd    -name   test1_opt   -summary "tcllib opt-based arg parsing"   -help "Accepts 10 keyed options plus -join. Uses tcl::OptProc for declaration and parsing."
+            @id     -id     ::argparsingtest::opts::opt
+            @cmd    -name   argparsingtest::opts::opt   -summary "tcllib opt-based arg parsing"   -help "Accepts 10 keyed options plus -join. Uses tcl::OptProc for declaration and parsing."
             @opts   -anyopts 0
             -return     -default string   -type string
             -frametype  -default \uFFEF   -type string
@@ -595,7 +1404,7 @@ namespace eval argparsingtest {
             -join       -type none   -multiple 1
         }]
     }
-    tcl::OptProc test1_opt {
+    tcl::OptProc opt {
         {-return string "return type"}
         {-frametype \uFFEF "type of frame"}
         {-show_edge \uFFEF "show table outer borders"}
@@ -615,12 +1424,11 @@ namespace eval argparsingtest {
         return $opts
     }
 
-    package require cmdline
     #cmdline::getoptions is much faster than typedGetoptions
     namespace eval argdoc {
         lappend PUNKARGS [list {
-            @id     -id     ::argparsingtest::test1_cmdline_untyped
-            @cmd    -name   test1_cmdline_untyped   -summary "cmdline getoptions untyped"   -help "Accepts 10 keyed options plus -join. Uses cmdline::getoptions (untyped, faster)."
+            @id     -id     ::argparsingtest::opts::cmdline_untyped
+            @cmd    -name   argparsingtest::opts::cmdline_untyped   -summary "cmdline getoptions untyped"   -help "Accepts 10 keyed options plus -join. Uses cmdline::getoptions (untyped, faster)."
             @opts   -anyopts 0
             -return     -default string   -type string
             -frametype  -default \uFFEF   -type string
@@ -635,7 +1443,7 @@ namespace eval argparsingtest {
             -join       -type none   -multiple 1
         }]
     }
-    proc test1_cmdline_untyped {args} {
+    proc cmdline_untyped {args} {
         set cmdlineopts_untyped {
             {return.arg   "string" "return val"}
             {frametype.arg \uFFEF "frame type"}
@@ -655,8 +1463,8 @@ namespace eval argparsingtest {
     }
     namespace eval argdoc {
         lappend PUNKARGS [list {
-            @id     -id     ::argparsingtest::test1_cmdline_typed
-            @cmd    -name   test1_cmdline_typed   -summary "cmdline typedGetoptions typed"   -help "Accepts 10 keyed options plus -join. Uses cmdline::typedGetoptions with typed specs."
+            @id     -id     ::argparsingtest::opts::cmdline_typed
+            @cmd    -name   argparsingtest::opts::cmdline_typed   -summary "cmdline typedGetoptions typed"   -help "Accepts 10 keyed options plus -join. Uses cmdline::typedGetoptions with typed specs."
             @opts   -anyopts 0
             -return     -default string   -type string
             -frametype  -default \uFFEF   -type string
@@ -671,7 +1479,7 @@ namespace eval argparsingtest {
             -join       -type none   -multiple 1
         }]
     }
-    proc test1_cmdline_typed {args} {
+    proc cmdline_typed {args} {
         set cmdlineopts_typed {
             {return.arg   "string" "return val"}
             {frametype.arg \uFFEF "frame type"}
@@ -693,16 +1501,16 @@ namespace eval argparsingtest {
     # Upstream argp 0.2 bug: argp::registerArgs (line 34) strips the leading
     # '::' from [namespace current] before building the caller key, but
     # argp::parseArgs (line 136) takes the raw [info level -1] command name
-    # with NO leading-'::' stripping. So a proc invoked as '::argparsingtest::test1_argp'
-    # is cmangled to '_argparsingtest_test1_argp' (spurious leading underscore
+    # with NO leading-'::' stripping. So a proc invoked as '::argparsingtest::opts::argp'
+    # is cmangled to '_argparsingtest_opts_argp' (spurious leading underscore
     # from string map {:: _}), which does not match the registration key
-    # 'argparsingtest_test1_argp'. Only calling as 'argparsingtest::test1_argp'
+    # 'argparsingtest_opts_argp'. Only calling as 'argparsingtest::opts::argp'
     # (no leading ::) happens to match. The timeit harness works around this
-    # by calling parsers as 'argparsingtest::<pname>' without the leading '::'.
+    # by calling parsers as 'argparsingtest::<style>::<pname>' without the leading '::'.
     # See: src/modules/argp-0.2.tm:34 (registerArgs) vs :136 (parseArgs).
     catch {
         package require argp
-        argp::registerArgs test1_argp {
+        argp::registerArgs argp {
         {    -return      string  "string"    }
         {    -frametype   string  \uFFEF    }
         {    -show_edge   string  \uFFEF    }
@@ -717,8 +1525,8 @@ namespace eval argparsingtest {
     }
     namespace eval argdoc {
         lappend PUNKARGS [list {
-            @id     -id     ::argparsingtest::test1_argp
-            @cmd    -name   test1_argp   -summary "argp package arg parsing"   -help "Accepts 10 keyed options plus -join. Uses argp::parseArgs for parsing."
+            @id     -id     ::argparsingtest::opts::argp
+            @cmd    -name   argparsingtest::opts::argp   -summary "argp package arg parsing"   -help "Accepts 10 keyed options. Uses argp::parseArgs for parsing."
             @opts   -anyopts 0
             -return     -default string   -type string
             -frametype  -default \uFFEF   -type string
@@ -730,19 +1538,17 @@ namespace eval argparsingtest {
             -1          -default 1        -type boolean
             -2          -default 2        -type integer
             -3          -default 3        -type integer
-            -join       -type none   -multiple 1
         }]
     }
-    proc test1_argp {args} {
+    proc argp {args} {
         argp::parseArgs opts
         return [array get opts]
     }
 
-    package require tepam
     namespace eval argdoc {
         lappend PUNKARGS [list {
-            @id     -id     ::argparsingtest::test1_tepam
-            @cmd    -name   test1_tepam   -summary "tepam procedure arg parsing"   -help "Accepts 10 keyed options plus -join. Uses tepam::procedure for declaration and parsing."
+            @id     -id     ::argparsingtest::opts::tepam
+            @cmd    -name   argparsingtest::opts::tepam   -summary "tepam procedure arg parsing"   -help "Accepts 10 keyed options plus -join. Uses tepam::procedure for declaration and parsing."
             @opts   -anyopts 0
             -return     -default string   -type string
             -frametype  -default \uFFEF   -type string
@@ -757,7 +1563,7 @@ namespace eval argparsingtest {
             -join       -type none   -multiple 1
         }]
     }
-    tepam::procedure {test1_tepam} {
+    tepam::procedure {tepam} {
     -args {
         {-return    -type string -default string}
         {-frametype -type string -default \uFFEF}
@@ -775,704 +1581,662 @@ namespace eval argparsingtest {
         return [dict create return $return frametype $frametype show_edge $show_edge show_seps $show_seps x $x y $y z $z 1 $1 2 $2 3 $3 join $join]
     }
 
-    #multiline values use first line of each record to determine amount of indent to trim
+    #*** !doctools
+    #[list_end] [comment {--- end definitions namespace argparsingtest::opts ---}]
+}
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+
+
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+# Parser implementations - tk style: 2 mandatory positional arguments FIRST,
+# then the 10 keyed options (as in: .canvas create rectangle 1 2 3 4 -fill red).
+# All procs return a 3-element list {p1 p2 opts} where opts is the parsed
+# options in the parser's natural form.
+# cmdline has no wrapper here: cmdline::getoptions stops consuming at the first
+# non-option word, so leading positionals defeat it (unsupported -> N/A row).
+# argp has no wrapper in any positional style: argp::parseArgs walks the entire
+# argument list as {key value} pairs, so any positional word errors as an
+# unknown option (unsupported -> N/A row).
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+namespace eval argparsingtest::tkstyle {
+    namespace export {[a-z]*}  ;# Convention: export all lowercase
+
+    #*** !doctools
+    #[subsection {Namespace argparsingtest::tkstyle}]
+    #[para] parser implementations - tk style: 2 leading positional arguments, then options
+    #[list_begin definitions]
+
     namespace eval argdoc {
         lappend PUNKARGS [list {
-            @id     -id     ::argparsingtest::test_multiline
-            @cmd    -name   test_multiline   -summary "multiline default value handling test"   -help "Tests punk::args multiline default indentation using subst."
+            @id     -id     ::argparsingtest::tkstyle::manual_switch
+            @cmd    -name   argparsingtest::tkstyle::manual_switch   -summary "manual parsing - tk style baseline"   -help\
+                "Accepts 2 leading positional arguments then 10 keyed options.
+                Positionals are plain proc formal parameters; options are validated
+                and collected via switch/dict set. Returns a list {p1 p2 optsdict}."
+            @leaders -min 2 -max 2
+            p1          -type string   -optional 0
+            p2          -type string   -optional 0
             @opts   -anyopts 0
-            -template1  -type string
-            -template2  -type string
-            -template3  -type string
-            -template3b -type string
-            -template4  -type string
-            -template5  -type string
-            -flag       -type boolean   -default 0
+            -return     -default string   -type string
+            -frametype  -default \uFFEF   -type string
+            -show_edge  -default \uFFEF   -type string
+            -show_seps  -default \uFFEF   -type string
+            -x          -default ""       -type string
+            -y          -default b        -type string
+            -z          -default c        -type string
+            -1          -default 1        -type boolean
+            -2          -default 2        -type integer
+            -3          -default 3        -type integer
         }]
     }
-    proc test_multiline {args} {
-        set t3 [textblock::frame t3]
-        set argd [punk::args::parse $args withdef [subst {
-            -template1 -default {
-                ******
-                * t1 *
-                ******
-            }
-                -template2 -default {    ------
-                    ******
-                    * t2 *
-                    ******}
-            -template3 -default {$t3}
-            #substituted or literal values with newlines - no autoindent applied - caller will have to pad appropriately
-            -template3b -default {
-            $t3
-            -----------------
-            $t3
-                   abc\ndef
+    proc manual_switch {p1 p2 args} {
+        set opts [dict create {*}{
+            -return     string
+            -frametype  \uFFEF
+            -show_edge  \uFFEF
+            -show_seps  \uFFEF
+            -x          ""
+            -y          b
+            -z          c
+            -1          1
+            -2          2
+            -3          3
+        }]
+        foreach {k v} $args {
+            switch -- $k {
+                -return - -show_edge - -show_seps - -frametype - -x - -y - -z - -1 - -2 - -3 {
+                    dict set opts $k $v
+                }
+                default {
+                    error "unrecognised option '$k'. Known options [dict keys $opts]"
+                }
             }
-            -template4 -default "******
-            * t4 *
-            ******"
-            -template5 -default "
-
-
-            "
-            -flag -default 0 -type boolean
-        }]]
-        return $argd
+        }
+        return [list $p1 $p2 $opts]
     }
+
     namespace eval argdoc {
         lappend PUNKARGS [list {
-            @id     -id     ::argparsingtest::test_multiline2
-            @cmd    -name   test_multiline2   -summary "multiline default value handling test 2"   -help "Tests punk::args multiline default indentation without subst."
+            @id     -id     ::argparsingtest::tkstyle::punkargs
+            @cmd    -name   argparsingtest::tkstyle::punkargs   -summary "punk::args withdef, tk style"   -help\
+                "Accepts 2 leading positional arguments then 10 keyed options plus -join.
+                Uses punk::args::parse withdef with an @leaders section.
+                Returns a list {p1 p2 optsdict}."
+            @leaders -min 2 -max 2
+            p1          -type string   -optional 0
+            p2          -type string   -optional 0
             @opts   -anyopts 0
-            -template1  -type string
-            -template2  -type string
-            -template3  -type string
-            -template3b -type string
-            -template4  -type string
-            -template5  -type string
-            -flag       -type boolean   -default 0
+            -return     -default string   -type string
+            -frametype  -default \uFFEF   -type string
+            -show_edge  -default \uFFEF   -type string
+            -show_seps  -default \uFFEF   -type string
+            -x          -default ""       -type string
+            -y          -default b        -type string
+            -z          -default c        -type string
+            -1          -default 1        -type boolean
+            -2          -default 2        -type integer
+            -3          -default 3        -type integer
+            -join       -type none   -multiple 1
         }]
     }
-    proc test_multiline2 {args} {
-        set t3 [textblock::frame t3]
+    proc punkargs {args} {
         set argd [punk::args::parse $args withdef {
-            -template1 -default {
-                ******
-                * t1 *
-                ******
-            }
-                -template2 -default {    ------
-                    ******
-                    * t2 *
-                    ******}
-            -template3 -default {$t3}
-            #substituted or literal values with newlines - no autoindent applied - caller will have to pad appropriately
-            -template3b -default {
-            ${$t3}
-            -----------------
-            ${$t3}
-                   abc\ndef
-            }
-            -template4 -default "******
-            * t4 *
-            ******"
-            -template5 -default "
-                a
-                    ${$t3}
-                        c
-            "
-            -flag -default 0 -type boolean
+            @id     -id  ::argparsingtest::tkstyle::punkargs
+            @cmd    -name argparsingtest::tkstyle::punkargs -help "test of punk::args::parse comparative performance"
+            @leaders -min 2 -max 2
+            p1          -type string -optional 0
+            p2          -type string -optional 0
+            @opts   -anyopts 0
+            -return     -default string -type string
+            -frametype  -default \uFFEF -type string
+            -show_edge  -default \uFFEF -type string
+            -show_seps  -default \uFFEF -type string
+            -join       -type none -multiple 1
+            -x          -default "" -type string
+            -y          -default b -type string
+            -z          -default c -type string
+            -1          -default 1 -type boolean
+            -2          -default 2 -type integer
+            -3          -default 3 -type integer
         }]
-        return $argd
+        set leaders [tcl::dict::get $argd leaders]
+        return [list [tcl::dict::get $leaders p1] [tcl::dict::get $leaders p2] [tcl::dict::get $argd opts]]
     }
 
-    #proc sample1 {p1 n args} {
-    #    #*** !doctools
-    #    #[call [fun sample1] [arg p1] [arg n] [opt {option value...}]]
-    #    #[para]Description of sample1
-    #    #[para] Arguments:
-    #    #   [list_begin arguments]
-    #    #   [arg_def tring p1]       A description of string argument p1.
-    #    #   [arg_def integer n]      A description of integer argument n.
-    #    #   [list_end]
-    #    return "ok"
-    #}
-
-
+    #Sole documentation source is the eager punk::args::define (load-time
+    #registration is part of what this variant measures) - see the
+    #opts::punkargs_by_id comment.
+    punk::args::define {
+        @id     -id ::argparsingtest::tkstyle::punkargs_by_id
+        @cmd    -name argparsingtest::tkstyle::punkargs_by_id\
+            -summary    "punk::args withid pre-registered, tk style"\
+            -help\
+                "Accepts 2 leading positional arguments then 10 keyed options plus -join.
+                Parses via a definition pre-registered at module load, using withid.
+                Returns a list {p1 p2 optsdict}."
+        @leaders -min 2 -max 2
+        p1          -type string -optional 0
+        p2          -type string -optional 0
+        @opts   -anyopts 0
+        -return     -default string -type string
+        -frametype  -default \uFFEF -type string
+        -show_edge  -default \uFFEF -type string
+        -show_seps  -default \uFFEF -type string
+        -join       -type none -multiple 1
+        -x          -default "" -type string
+        -y          -default b -type string
+        -z          -default c -type string
+        -1          -default 1 -type boolean
+        -2          -default 2 -type integer
+        -3          -default 3 -type integer
+    }
+    proc punkargs_by_id {args} {
+        set argd [punk::args::parse $args withid ::argparsingtest::tkstyle::punkargs_by_id]
+        set leaders [tcl::dict::get $argd leaders]
+        return [list [tcl::dict::get $leaders p1] [tcl::dict::get $leaders p2] [tcl::dict::get $argd opts]]
+    }
 
+    namespace eval argdoc {
+        lappend PUNKARGS [list {
+            @id     -id     ::argparsingtest::tkstyle::punkargs_parsecache
+            @cmd    -name   argparsingtest::tkstyle::punkargs_parsecache   -summary "punk::args withid with parse cache, tk style"   -help\
+                "Accepts 2 leading positional arguments then 10 keyed options plus -join.
+                Uses withid and -cache 1 for repeated parse reuse.
+                Returns a list {p1 p2 optsdict}."
+            @leaders -min 2 -max 2
+            p1          -type string   -optional 0
+            p2          -type string   -optional 0
+            @opts   -anyopts 0
+            -return     -default string   -type string
+            -frametype  -default \uFFEF   -type string
+            -show_edge  -default \uFFEF   -type string
+            -show_seps  -default \uFFEF   -type string
+            -x          -default ""       -type string
+            -y          -default b        -type string
+            -z          -default c        -type string
+            -1          -default 1        -type boolean
+            -2          -default 2        -type integer
+            -3          -default 3        -type integer
+            -join       -type none   -multiple 1
+        }]
+    }
+    proc punkargs_parsecache {args} {
+        set argd [punk::args::parse $args -cache 1 withid ::argparsingtest::tkstyle::punkargs_by_id]
+        set leaders [tcl::dict::get $argd leaders]
+        return [list [tcl::dict::get $leaders p1] [tcl::dict::get $leaders p2] [tcl::dict::get $argd opts]]
+    }
 
     namespace eval argdoc {
         lappend PUNKARGS [list {
-            @id     -id     ::argparsingtest::discover_parsers
-            @cmd    -name   discover_parsers\
-                -summary    "Discover available argument parsers"\
-                -help\
-                    "Returns a dict of parser proc names to their load status.
-
-                    Each key is a parser proc name. Values are one of:
-                      loaded       - proc callable; timed by default
-                      not_loaded   - backing package absent; proc must not be called
-                      not_wrappable - optional package present but no timing wrapper shipped"
+            @id     -id     ::argparsingtest::tkstyle::opt
+            @cmd    -name   argparsingtest::tkstyle::opt   -summary "tcllib opt-based arg parsing, tk style"   -help\
+                "Accepts 2 leading positional arguments then 10 keyed options plus -join.
+                Uses tcl::OptProc with the positionals declared first in the spec.
+                Returns a list {p1 p2 optsdict}."
+            @leaders -min 2 -max 2
+            p1          -type string   -optional 0
+            p2          -type string   -optional 0
+            @opts   -anyopts 0
+            -return     -default string   -type string
+            -frametype  -default \uFFEF   -type string
+            -show_edge  -default \uFFEF   -type string
+            -show_seps  -default \uFFEF   -type string
+            -x          -default ""       -type string
+            -y          -default b        -type string
+            -z          -default c        -type string
+            -1          -default 1        -type boolean
+            -2          -default 2        -type integer
+            -3          -default 3        -type integer
+            -join       -type none   -multiple 1
         }]
     }
-    proc discover_parsers {} {
-        # discover_parsers - return dict of parser proc names to load status
-        set result {}
-
-        # Always-loaded set: backed by unconditional package requires or no require
-        foreach pname {
-            test1_ni
-            test1_switchmerge
-            test1_switch
-            test1_switch_nsvar
-            test1_switch2
-            test1_prefix
-            test1_prefix2
-            test1_punkargs
-            test1_punkargs_any
-            test1_punkargs_by_id
-            test1_punkargs_parsecache
-            test1_punkargs_validate_ansistripped
-            test1_opt
-            test1_cmdline_untyped
-            test1_cmdline_typed
-            test1_tepam
-        } {
-            dict set result $pname loaded
-        }
-
-        # argp: proc defined unconditionally but registration guarded by catch at module load;
-        # use package present to check whether the load-time require succeeded (no side effects)
-        if {[catch {package present argp}]} {
-            dict set result test1_argp not_loaded
-        } else {
-            dict set result test1_argp loaded
-        }
-
-        # Optional externals: probe with package require; no timing wrappers shipped for these four
-        foreach {pname pkg} {
-            test1_getopt      getopt
-            test1_parse_args  parse_args
-            test1_argparse    argparse
-            test1_cmdr        cmdr
-        } {
-            if {[catch {package require $pkg}]} {
-                dict set result $pname not_loaded
-            } else {
-                dict set result $pname not_wrappable
+    tcl::OptProc opt {
+        {p1 -string "first positional argument"}
+        {p2 -string "second positional argument"}
+        {-return string "return type"}
+        {-frametype \uFFEF "type of frame"}
+        {-show_edge \uFFEF "show table outer borders"}
+        {-show_seps \uFFEF "show separators"}
+        {-join "solo option"}
+        {-x "" "x val"}
+        {-y b "y val"}
+        {-z c "z val"}
+        {-1 1 "1val"}
+        {-2 -int 2  "2val"}
+        {-3 -int 3 "3val"}
+    } {
+        set opts [dict create]
+        foreach v [info locals] {
+            if {$v ni {p1 p2 opts args Args}} {
+                dict set opts $v [set $v]
             }
         }
-
-        return $result
+        return [list $p1 $p2 $opts]
     }
 
-    punk::args::define {
-        @id     -id     ::argparsingtest::timeit
-        @cmd    -name   timeit\
-            -summary    "Time argument parser performance"\
-            -help\
-                "Runs rough timing comparisons across argument parsers.
-
-                Returns a dict mapping each parser proc name to timing results.
-                Each value is a sub-dict with keys:
-                  us_per_call   - mean microseconds per call
-                  calls_per_sec - mean calls per second
-                  iterations    - iteration count used
-                  warmup        - warmup count used
-                Parsers that error during timing return {error <message>} instead."
-        @opts   -anyopts 0
-            -iterations -default 1000 -type integer -help\
-                "Number of timed invocations per parser."
-            -warmup     -default 1    -type integer -help\
-                "Number of untimed warmup invocations before timing starts."
-            -parsers    -default {}   -type list    -help\
-                "List of parser proc names to time. Empty (default) times
-                  all discovered loaded parsers."
-            -args       -default {-return object -x hello -y world -1 1 -2 2 -3 3} -type list -help\
-                "Argument vector passed to each parser proc during timing."
+    namespace eval argdoc {
+        lappend PUNKARGS [list {
+            @id     -id     ::argparsingtest::tkstyle::tepam
+            @cmd    -name   argparsingtest::tkstyle::tepam   -summary "tepam procedure arg parsing, tk style"   -help\
+                "Accepts 2 leading positional arguments then 10 keyed options plus -join.
+                Uses tepam::procedure with -named_arguments_first 0 (unnamed arguments
+                lead). Returns a list {p1 p2 optsdict}."
+            @leaders -min 2 -max 2
+            p1          -type string   -optional 0
+            p2          -type string   -optional 0
+            @opts   -anyopts 0
+            -return     -default string   -type string
+            -frametype  -default \uFFEF   -type string
+            -show_edge  -default \uFFEF   -type string
+            -show_seps  -default \uFFEF   -type string
+            -x          -default ""       -type string
+            -y          -default b        -type string
+            -z          -default c        -type string
+            -1          -default 1        -type boolean
+            -2          -default 2        -type integer
+            -3          -default 3        -type integer
+            -join       -type none   -multiple 1
+        }]
+    }
+    tepam::procedure {tepam} {
+    -named_arguments_first 0
+    -args {
+        {p1 -type string}
+        {p2 -type string}
+        {-return    -type string -default string}
+        {-frametype -type string -default \uFFEF}
+        {-show_edge -type string -default \uFFEF}
+        {-show_seps -type string -default \uFFEF}
+        {-join      -type none -multiple}
+        {-x         -type string -default ""}
+        {-y         -type string -default b}
+        {-z         -type string -default c}
+        {-1         -type boolean -default 1}
+        {-2         -type integer -default 2}
+        {-3         -type integer -default 3}
+    }
+    } {
+        return [list $p1 $p2 [dict create return $return frametype $frametype show_edge $show_edge show_seps $show_seps x $x y $y z $z 1 $1 2 $2 3 $3 join $join]]
     }
-    proc timeit {args} {
-        # timeit - time argument parser performance, returns dict of {parser -> timing_info}
-        set argd [punk::args::parse $args withid ::argparsingtest::timeit]
-        set iterations [dict get $argd opts -iterations]
-        set warmup     [dict get $argd opts -warmup]
-        set parsers    [dict get $argd opts -parsers]
-        set argvec     [dict get $argd opts -args]
-
-        if {[llength $parsers] == 0} {
-            set discovered [discover_parsers]
-            set parsers {}
-            foreach {pname status} $discovered {
-                if {$status eq "loaded"} {
-                    lappend parsers $pname
-                }
-            }
-        }
-
-        set result {}
-        foreach pname $parsers {
-            set had_error 0
-            set err_msg {}
-
-            # Use namespace-qualified name (without leading ::) so argp::parseArgs
-            # (which uses info level -1 to identify the caller) can match the
-            # registration stored under argparsingtest::<pname>. Calling unqualified
-            # breaks argp scoping; calling with leading :: also breaks it because
-            # string map {:: _} adds a spurious leading underscore.
-            set fqname argparsingtest::$pname
-
-            for {set i 0} {$i < $warmup} {incr i} {
-                try {
-                    $fqname {*}$argvec
-                } on error {err_result _err_opts} {
-                    set had_error 1
-                    set err_msg $err_result
-                    break
-                }
-            }
-            if {$had_error} {
-                dict set result $pname [list error $err_msg]
-                continue
-            }
 
-            set start [clock microseconds]
-            for {set i 0} {$i < $iterations} {incr i} {
-                try {
-                    $fqname {*}$argvec
-                } on error {err_result _err_opts} {
-                    set had_error 1
-                    set err_msg $err_result
-                    break
-                }
-            }
-            set end [clock microseconds]
+    #*** !doctools
+    #[list_end] [comment {--- end definitions namespace argparsingtest::tkstyle ---}]
+}
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
 
-            if {$had_error} {
-                dict set result $pname [list error $err_msg]
-                continue
-            }
 
-            set us_per_call   [expr {double($end - $start) / $iterations}]
-            set calls_per_sec [expr {1000000.0 / $us_per_call}]
-            set timing {}
-            dict set timing us_per_call   $us_per_call
-            dict set timing calls_per_sec $calls_per_sec
-            dict set timing iterations    $iterations
-            dict set timing warmup        $warmup
-            dict set result $pname $timing
-        }
-        return $result
-    }
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+# Parser implementations - tcl style: the 10 keyed options FIRST, then 2
+# mandatory positional arguments (as in: lsearch -exact $list $val).
+# All procs return a 3-element list {p1 p2 opts} where opts is the parsed
+# options in the parser's natural form.
+# cmdline IS supported here: cmdline::getoptions consumes leading options and
+# leaves the trailing positionals in the caller's args variable.
+# argp has no wrapper (see the tkstyle namespace comment; unsupported -> N/A row).
+# ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
+namespace eval argparsingtest::tclstyle {
+    namespace export {[a-z]*}  ;# Convention: export all lowercase
 
-    # Per-library warm-up scripts for first_call's 'warm' timing mode.
-    # Keyed by parser proc name; absent key = hand-rolled parser with no
-    # backing library (nothing to pre-compile).
-    # Each script exercises the parser's backing library through sacrificial
-    # definitions/procs so the library's internals are byte-compiled before
-    # the timed first call. Warm-ups must never touch the definition or
-    # registration of the proc under test - resolving those is legitimately
-    # part of that proc's first-call cost.
-    variable library_warmups
-    set library_warmups [dict create]
+    #*** !doctools
+    #[subsection {Namespace argparsingtest::tclstyle}]
+    #[para] parser implementations - tcl style: options first, 2 trailing positional arguments
+    #[list_begin definitions]
 
-    # punk::args-backed parsers share one warm-up covering the withid, withdef
-    # and -cache 1 paths plus the option types/features the test1_punkargs*
-    # variants use (string/integer/boolean/none types, -multiple, -choices,
-    # -validate_ansistripped).
-    set punkargs_warmup {
-        punk::args::define {
-            @id     -id ::argparsingtest::libwarmup
-            @cmd    -name libwarmup -help "sacrificial definition for punk::args warm-up"
-            @opts   -anyopts 0
-            -wstr   -default a -type string -choices {a x}
-            -wint   -default 1 -type integer -validate_ansistripped true
-            -wbool  -default 0 -type boolean
-            -wsolo  -type none -multiple 1
-            @values
-        }
-        punk::args::parse {-wstr x -wint 2 -wbool 1 -wsolo} withid ::argparsingtest::libwarmup
-        punk::args::parse {-wstr x} -cache 1 withid ::argparsingtest::libwarmup
-        punk::args::parse {-wstr x} withdef {
-            @id     -id ::argparsingtest::libwarmup_withdef
+    namespace eval argdoc {
+        lappend PUNKARGS [list {
+            @id     -id     ::argparsingtest::tclstyle::manual_switch
+            @cmd    -name   argparsingtest::tclstyle::manual_switch   -summary "manual parsing - tcl style baseline"   -help\
+                "Accepts 10 keyed options then 2 trailing positional arguments.
+                Peels the fixed 2 positionals from the end of args, then validates
+                and collects options via switch/dict set. Returns a list {p1 p2 optsdict}."
             @opts   -anyopts 0
-            -wstr   -default a -type string
-        }
-    }
-    foreach pname {
-        test1_punkargs
-        test1_punkargs_any
-        test1_punkargs_by_id
-        test1_punkargs_parsecache
-        test1_punkargs_validate_ansistripped
-    } {
-        dict set library_warmups $pname $punkargs_warmup
-    }
-    unset pname punkargs_warmup
-
-    dict set library_warmups test1_opt {
-        tcl::OptProc ::argparsingtest::libwarmup_opt {
-            {-w 0 "warm-up option"}
-        } {
-            return [info locals]
-        }
-        ::argparsingtest::libwarmup_opt -w 1
-    }
-    dict set library_warmups test1_cmdline_untyped {
-        set libwarmup_args {-w 1}
-        cmdline::getoptions libwarmup_args {
-            {w.arg 0 "warm-up option"}
-        } "usage"
-    }
-    dict set library_warmups test1_cmdline_typed {
-        set libwarmup_args {-w 1}
-        cmdline::typedGetoptions libwarmup_args {
-            {w.integer 0 "warm-up option"}
-        } "usage"
+            -return     -default string   -type string
+            -frametype  -default \uFFEF   -type string
+            -show_edge  -default \uFFEF   -type string
+            -show_seps  -default \uFFEF   -type string
+            -x          -default ""       -type string
+            -y          -default b        -type string
+            -z          -default c        -type string
+            -1          -default 1        -type boolean
+            -2          -default 2        -type integer
+            -3          -default 3        -type integer
+            @values -min 2 -max 2
+            p1          -type string   -optional 0
+            p2          -type string   -optional 0
+        }]
     }
-    dict set library_warmups test1_tepam {
-        tepam::procedure libwarmup_tepam {
-            -args {
-                {-w -type integer -default 0}
-            }
-        } {
-            return $w
+    proc manual_switch {args} {
+        if {[llength $args] < 2} {
+            error "expected at least 2 arguments - trailing positional arguments p1 p2 are mandatory"
         }
-        libwarmup_tepam -w 1
-    }
-    # argp caller-key mangling (see the test1_argp registration site): register
-    # inside the argparsingtest namespace and call without a leading '::' so
-    # registerArgs' key matches parseArgs' caller lookup.
-    dict set library_warmups test1_argp {
-        namespace eval ::argparsingtest {
-            argp::registerArgs libwarmup_argp {
-                {-w integer 0}
-            }
-            proc libwarmup_argp {args} {
-                argp::parseArgs opts
-                return [array get opts]
+        set p1 [lindex $args end-1]
+        set p2 [lindex $args end]
+        set args [lrange $args 0 end-2]
+        set opts [dict create {*}{
+            -return     string
+            -frametype  \uFFEF
+            -show_edge  \uFFEF
+            -show_seps  \uFFEF
+            -x          ""
+            -y          b
+            -z          c
+            -1          1
+            -2          2
+            -3          3
+        }]
+        foreach {k v} $args {
+            switch -- $k {
+                -return - -show_edge - -show_seps - -frametype - -x - -y - -z - -1 - -2 - -3 {
+                    dict set opts $k $v
+                }
+                default {
+                    error "unrecognised option '$k'. Known options [dict keys $opts]"
+                }
             }
         }
-        argparsingtest::libwarmup_argp -w 1
+        return [list $p1 $p2 $opts]
     }
 
-    punk::args::define {
-        @id     -id     ::argparsingtest::first_call
-        @cmd    -name   first_call\
-            -summary    "Time cold and warm first-call cost of each argument parser"\
-            -help\
-                "Creates fresh child interpreters for each parser and times
-                the first invocation after loading the argparsingtest module.
-                Child interps load the parent's exact package versions of
-                argparsingtest, punk::args and (when present) punk::lib so the
-                module timed is the one under test rather than any older
-                stable copy visible on the module paths.
-
-                Each parser is timed twice, in separate child interps:
-                  cold - first call immediately after package load. Includes
-                         byte-compilation of the parser proc body and of any
-                         backing-library procs it invokes.
-                  warm - the parser's backing library is first exercised via a
-                         sacrificial definition/proc distinct from the one under
-                         test, so library internals are already byte-compiled
-                         when the timed call runs. This isolates the per-proc
-                         first-use cost (definition resolution, registration
-                         lookup, proc body compile). Hand-rolled parsers have no
-                         backing library to warm; their warm figure is simply a
-                         second cold measurement.
+    namespace eval argdoc {
+        lappend PUNKARGS [list {
+            @id     -id     ::argparsingtest::tclstyle::punkargs
+            @cmd    -name   argparsingtest::tclstyle::punkargs   -summary "punk::args withdef, tcl style"   -help\
+                "Accepts 10 keyed options plus -join, then 2 trailing positional arguments.
+                Uses punk::args::parse withdef with an @values section.
+                Returns a list {p1 p2 optsdict}."
+            @opts   -anyopts 0
+            -return     -default string   -type string
+            -frametype  -default \uFFEF   -type string
+            -show_edge  -default \uFFEF   -type string
+            -show_seps  -default \uFFEF   -type string
+            -x          -default ""       -type string
+            -y          -default b        -type string
+            -z          -default c        -type string
+            -1          -default 1        -type boolean
+            -2          -default 2        -type integer
+            -3          -default 3        -type integer
+            -join       -type none   -multiple 1
+            @values -min 2 -max 2
+            p1          -type string   -optional 0
+            p2          -type string   -optional 0
+        }]
+    }
+    proc punkargs {args} {
+        set argd [punk::args::parse $args withdef {
+            @id     -id  ::argparsingtest::tclstyle::punkargs
+            @cmd    -name argparsingtest::tclstyle::punkargs -help "test of punk::args::parse comparative performance"
+            @opts   -anyopts 0
+            -return     -default string -type string
+            -frametype  -default \uFFEF -type string
+            -show_edge  -default \uFFEF -type string
+            -show_seps  -default \uFFEF -type string
+            -join       -type none -multiple 1
+            -x          -default "" -type string
+            -y          -default b -type string
+            -z          -default c -type string
+            -1          -default 1 -type boolean
+            -2          -default 2 -type integer
+            -3          -default 3 -type integer
+            @values -min 2 -max 2
+            p1          -type string -optional 0
+            p2          -type string -optional 0
+        }]
+        set values [tcl::dict::get $argd values]
+        return [list [tcl::dict::get $values p1] [tcl::dict::get $values p2] [tcl::dict::get $argd opts]]
+    }
 
-                Returns a dict mapping each parser name to a sub-dict with keys
-                cold and warm. Each value is that run's first-call microseconds
-                (float), or {error <message>} if the run fails in the child
-                interp."
+    #Sole documentation source is the eager punk::args::define (load-time
+    #registration is part of what this variant measures) - see the
+    #opts::punkargs_by_id comment.
+    punk::args::define {
+        @id     -id ::argparsingtest::tclstyle::punkargs_by_id
+        @cmd    -name argparsingtest::tclstyle::punkargs_by_id\
+            -summary    "punk::args withid pre-registered, tcl style"\
+            -help\
+                "Accepts 10 keyed options plus -join, then 2 trailing positional arguments.
+                Parses via a definition pre-registered at module load, using withid.
+                Returns a list {p1 p2 optsdict}."
         @opts   -anyopts 0
-            -parsers    -default {}   -type list    -help\
-                "List of parser proc names to time. Empty (default) times
-                  all discovered loaded parsers."
+        -return     -default string -type string
+        -frametype  -default \uFFEF -type string
+        -show_edge  -default \uFFEF -type string
+        -show_seps  -default \uFFEF -type string
+        -join       -type none -multiple 1
+        -x          -default "" -type string
+        -y          -default b -type string
+        -z          -default c -type string
+        -1          -default 1 -type boolean
+        -2          -default 2 -type integer
+        -3          -default 3 -type integer
+        @values -min 2 -max 2
+        p1          -type string -optional 0
+        p2          -type string -optional 0
+    }
+    proc punkargs_by_id {args} {
+        set argd [punk::args::parse $args withid ::argparsingtest::tclstyle::punkargs_by_id]
+        set values [tcl::dict::get $argd values]
+        return [list [tcl::dict::get $values p1] [tcl::dict::get $values p2] [tcl::dict::get $argd opts]]
     }
+
     namespace eval argdoc {
         lappend PUNKARGS [list {
-            @id     -id     ::argparsingtest::first_call
-            @cmd    -name   first_call\
-                -summary    "Time cold and warm first-call cost of each argument parser"\
-                -help\
-                    "Creates fresh child interpreters for each parser and times
-                    the first invocation after loading the argparsingtest module.
-                    Child interps load the parent's exact package versions of
-                    argparsingtest, punk::args and (when present) punk::lib so the
-                    module timed is the one under test rather than any older
-                    stable copy visible on the module paths.
-
-                    Each parser is timed twice, in separate child interps:
-                      cold - first call immediately after package load. Includes
-                             byte-compilation of the parser proc body and of any
-                             backing-library procs it invokes.
-                      warm - the parser's backing library is first exercised via a
-                             sacrificial definition/proc distinct from the one under
-                             test, so library internals are already byte-compiled
-                             when the timed call runs. This isolates the per-proc
-                             first-use cost (definition resolution, registration
-                             lookup, proc body compile). Hand-rolled parsers have no
-                             backing library to warm; their warm figure is simply a
-                             second cold measurement.
-
-                    Returns a dict mapping each parser name to a sub-dict with keys
-                    cold and warm. Each value is that run's first-call microseconds
-                    (float), or {error <message>} if the run fails in the child
-                    interp."
+            @id     -id     ::argparsingtest::tclstyle::punkargs_parsecache
+            @cmd    -name   argparsingtest::tclstyle::punkargs_parsecache   -summary "punk::args withid with parse cache, tcl style"   -help\
+                "Accepts 10 keyed options plus -join, then 2 trailing positional arguments.
+                Uses withid and -cache 1 for repeated parse reuse.
+                Returns a list {p1 p2 optsdict}."
             @opts   -anyopts 0
-                -parsers    -default {}   -type list    -help\
-                    "List of parser proc names to time. Empty (default) times
-                      all discovered loaded parsers."
+            -return     -default string   -type string
+            -frametype  -default \uFFEF   -type string
+            -show_edge  -default \uFFEF   -type string
+            -show_seps  -default \uFFEF   -type string
+            -x          -default ""       -type string
+            -y          -default b        -type string
+            -z          -default c        -type string
+            -1          -default 1        -type boolean
+            -2          -default 2        -type integer
+            -3          -default 3        -type integer
+            -join       -type none   -multiple 1
+            @values -min 2 -max 2
+            p1          -type string   -optional 0
+            p2          -type string   -optional 0
         }]
     }
-    proc first_call {args} {
-        # first_call - time cold and warm first-call cost of each parser in fresh child interps
-        set argd [punk::args::parse $args withid ::argparsingtest::first_call]
-        set parsers [dict get $argd opts -parsers]
-
-        variable library_warmups
-
-        set argvec {-return object -x hello -y world -1 1 -2 2 -3 3}
+    proc punkargs_parsecache {args} {
+        set argd [punk::args::parse $args -cache 1 withid ::argparsingtest::tclstyle::punkargs_by_id]
+        set values [tcl::dict::get $argd values]
+        return [list [tcl::dict::get $values p1] [tcl::dict::get $values p2] [tcl::dict::get $argd opts]]
+    }
 
-        if {[llength $parsers] == 0} {
-            set discovered [discover_parsers]
-            set parsers {}
-            foreach {pname status} $discovered {
-                if {$status eq "loaded"} {
-                    lappend parsers $pname
-                }
+    namespace eval argdoc {
+        lappend PUNKARGS [list {
+            @id     -id     ::argparsingtest::tclstyle::opt
+            @cmd    -name   argparsingtest::tclstyle::opt   -summary "tcllib opt-based arg parsing, tcl style"   -help\
+                "Accepts 10 keyed options plus -join, then 2 trailing positional arguments.
+                Uses tcl::OptProc with the positionals declared last in the spec.
+                Returns a list {p1 p2 optsdict}."
+            @opts   -anyopts 0
+            -return     -default string   -type string
+            -frametype  -default \uFFEF   -type string
+            -show_edge  -default \uFFEF   -type string
+            -show_seps  -default \uFFEF   -type string
+            -x          -default ""       -type string
+            -y          -default b        -type string
+            -z          -default c        -type string
+            -1          -default 1        -type boolean
+            -2          -default 2        -type integer
+            -3          -default 3        -type integer
+            -join       -type none   -multiple 1
+            @values -min 2 -max 2
+            p1          -type string   -optional 0
+            p2          -type string   -optional 0
+        }]
+    }
+    tcl::OptProc opt {
+        {-return string "return type"}
+        {-frametype \uFFEF "type of frame"}
+        {-show_edge \uFFEF "show table outer borders"}
+        {-show_seps \uFFEF "show separators"}
+        {-join "solo option"}
+        {-x "" "x val"}
+        {-y b "y val"}
+        {-z c "z val"}
+        {-1 1 "1val"}
+        {-2 -int 2  "2val"}
+        {-3 -int 3 "3val"}
+        {p1 -string "first positional argument"}
+        {p2 -string "second positional argument"}
+    } {
+        set opts [dict create]
+        foreach v [info locals] {
+            if {$v ni {p1 p2 opts args Args}} {
+                dict set opts $v [set $v]
             }
         }
+        return [list $p1 $p2 $opts]
+    }
 
-        # Capture parent interp's module paths and auto_path for transfer to children
-        set tm_paths [tcl::tm::list]
-        set ap $::auto_path
-
-        # Pin the child's package requires to the versions loaded in the parent.
-        # Plain 'package require' prefers stable versions, so a dev/alpha module
-        # loaded in the parent would otherwise be shadowed in the child by any
-        # older stable copy visible on the module paths - the child would then
-        # time a different module than the one under test. punk::lib is included
-        # (when the parent has it) because it provides the lpop compat shim that
-        # punk::args::parse needs under Tcl 8.6; require order matters - pin
-        # punk::args before punk::lib/argparsingtest so their own plain
-        # 'package require punk::args' calls resolve to the pinned version.
-        set pinned_requires ""
-        foreach pkg {punk::args punk::lib argparsingtest} {
-            if {![catch {package present $pkg} ver]} {
-                append pinned_requires "package require -exact [list $pkg] [list $ver]\n"
-            }
+    namespace eval argdoc {
+        lappend PUNKARGS [list {
+            @id     -id     ::argparsingtest::tclstyle::cmdline_untyped
+            @cmd    -name   argparsingtest::tclstyle::cmdline_untyped   -summary "cmdline getoptions untyped, tcl style"   -help\
+                "Accepts 10 keyed options plus -join, then 2 trailing positional arguments.
+                cmdline::getoptions consumes the leading options and leaves the
+                positionals in the args variable; the wrapper enforces exactly 2.
+                Returns a list {p1 p2 optsdict}."
+            @opts   -anyopts 0
+            -return     -default string   -type string
+            -frametype  -default \uFFEF   -type string
+            -show_edge  -default \uFFEF   -type string
+            -show_seps  -default \uFFEF   -type string
+            -x          -default ""       -type string
+            -y          -default b        -type string
+            -z          -default c        -type string
+            -1          -default 1        -type boolean
+            -2          -default 2        -type integer
+            -3          -default 3        -type integer
+            -join       -type none   -multiple 1
+            @values -min 2 -max 2
+            p1          -type string   -optional 0
+            p2          -type string   -optional 0
+        }]
+    }
+    proc cmdline_untyped {args} {
+        set cmdlineopts_untyped {
+            {return.arg   "string" "return val"}
+            {frametype.arg \uFFEF "frame type"}
+            {show_edge.arg \uFFEF "show table borders"}
+            {show_seps.arg \uFFEF "show table seps"}
+            {join        "join the things"}
+            {x.arg  ""  "arg x"}
+            {y.arg  b  "arg y"}
+            {z.arg  c  "arg z"}
+            {1.arg  1  "arg 1"}
+            {2.arg  2  "arg 2"}
+            {3.arg  3  "arg 3"}
         }
 
-        set result {}
-        foreach pname $parsers {
-            set timings {}
-            foreach mode {cold warm} {
-                if {$mode eq "warm" && [dict exists $library_warmups $pname]} {
-                    set warmup [dict get $library_warmups $pname]
-                } else {
-                    #cold run - or warm run for a parser with no backing library (nothing to pre-compile)
-                    set warmup ""
-                }
-                set child [interp create]
-                try {
-                    # Clear child's tm list and auto_path (which come from the
-                    # environment) then set them to match the parent interp so
-                    # module resolution is identical.
-                    set child_tm [interp eval $child {tcl::tm::list}]
-                    if {[llength $child_tm]} {
-                        interp eval $child [list tcl::tm::path remove {*}$child_tm]
-                    }
-                    interp eval $child [list set ::auto_path $ap]
-                    if {[llength $tm_paths]} {
-                        interp eval $child [list tcl::tm::path add {*}$tm_paths]
-                    }
-
-                    # Load the module (pinned to parent's versions), run any
-                    # library warm-up, then time the FIRST call to this parser.
-                    # Build a script with the requires, warmup, pname and argvec
-                    # substituted into place, using expand-style per AGENTS.md.
-                    set script [string cat\
-                        $pinned_requires\
-                        $warmup                                     {*}{
-                        "\nset start \[clock microseconds]\n"
-                    }   "argparsingtest::$pname $argvec\n"          {*}{
-                        "set end \[clock microseconds]\n"
-                        "return \[expr {double(\$end - \$start)}]"
-                    }]
-                    if {[catch {interp eval $child $script} us_val us_opts]} {
-                        dict set timings $mode [list error $us_val]
-                    } else {
-                        dict set timings $mode $us_val
-                    }
-                } on error {err opts} {
-                    dict set timings $mode [list error $err]
-                } finally {
-                    interp delete $child
-                }
-            }
-            dict set result $pname $timings
+        set usage "usage etc"
+        set opts [::cmdline::getoptions args $cmdlineopts_untyped $usage]
+        if {[llength $args] != 2} {
+            error "expected exactly 2 trailing positional arguments, got [llength $args]"
         }
-        return $result
-    }
-
-    punk::args::define {
-        @id     -id     ::argparsingtest::compare
-        @cmd    -name   compare\
-            -summary    "Compare argument parser performance"\
-            -help\
-                "Runs timing comparisons and outputs results as table, dict, or json.
-
-                Returns a formatted comparison of all loaded argument parsers.
-                Rows are sorted fastest-first (ascending us_per_call).
-                - table: human-readable matrix sorted by us_per_call ascending
-                         (first_cold/first_warm columns are first_call timings)
-                - dict:  {results <timeit_dict> first_call <first_call_dict> not_loaded <list>}
-                         first_call values are {cold <us> warm <us>} sub-dicts (see first_call)
-                - json:  JSON object with results, first_call, and not_loaded keys"
-        @opts   -anyopts 0
-            -format     -default table   -type string  -choices {table dict json} -help\
-                "Output format: table (default), dict, or json."
-            -iterations -default 1000    -type integer -help\
-                "Number of timed invocations per parser."
-            -warmup     -default 1       -type integer -help\
-                "Number of untimed warmup invocations before timing starts."
-            -parsers    -default {}      -type list    -help\
-                "List of parser proc names to time. Empty (default) times
-                  all discovered loaded parsers."
-            -args       -default {-return object -x hello -y world -1 1 -2 2 -3 3} -type list -help\
-                "Argument vector passed to each parser proc during timing."
+        return [list [lindex $args 0] [lindex $args 1] $opts]
     }
     namespace eval argdoc {
         lappend PUNKARGS [list {
-            @id     -id     ::argparsingtest::compare
-            @cmd    -name   compare\
-                -summary    "Compare argument parser performance"\
-                -help\
-                    "Runs timing comparisons and outputs results as table, dict, or json.
-
-                    Returns a formatted comparison of all loaded argument parsers.
-                    Rows are sorted fastest-first (ascending us_per_call).
-                    - table: human-readable matrix sorted by us_per_call ascending
-                             (first_cold/first_warm columns are first_call timings)
-                    - dict:  {results <timeit_dict> first_call <first_call_dict> not_loaded <list>}
-                             first_call values are {cold <us> warm <us>} sub-dicts (see first_call)
-                    - json:  JSON object with results, first_call, and not_loaded keys"
+            @id     -id     ::argparsingtest::tclstyle::cmdline_typed
+            @cmd    -name   argparsingtest::tclstyle::cmdline_typed   -summary "cmdline typedGetoptions typed, tcl style"   -help\
+                "Accepts 10 keyed options plus -join, then 2 trailing positional arguments.
+                cmdline::typedGetoptions consumes the leading options and leaves the
+                positionals in the args variable; the wrapper enforces exactly 2.
+                Returns a list {p1 p2 optsdict}."
             @opts   -anyopts 0
-                -format     -default table   -type string  -choices {table dict json} -help\
-                    "Output format: table (default), dict, or json."
-                -iterations -default 1000    -type integer -help\
-                    "Number of timed invocations per parser."
-                -warmup     -default 1       -type integer -help\
-                    "Number of untimed warmup invocations before timing starts."
-                -parsers    -default {}      -type list    -help\
-                    "List of parser proc names to time. Empty (default) times
-                      all discovered loaded parsers."
-                -args       -default {-return object -x hello -y world -1 1 -2 2 -3 3} -type list -help\
-                    "Argument vector passed to each parser proc during timing."
+            -return     -default string   -type string
+            -frametype  -default \uFFEF   -type string
+            -show_edge  -default \uFFEF   -type string
+            -show_seps  -default \uFFEF   -type string
+            -x          -default ""       -type string
+            -y          -default b        -type string
+            -z          -default c        -type string
+            -1          -default 1        -type boolean
+            -2          -default 2        -type integer
+            -3          -default 3        -type integer
+            -join       -type none   -multiple 1
+            @values -min 2 -max 2
+            p1          -type string   -optional 0
+            p2          -type string   -optional 0
         }]
     }
-    proc compare {args} {
-        # compare - compare argument parser performance, returns formatted table/dict/json
-        set argd [punk::args::parse $args withid ::argparsingtest::compare]
-        set fmt        [dict get $argd opts -format]
-        set iterations [dict get $argd opts -iterations]
-        set warmup     [dict get $argd opts -warmup]
-        set parsers    [dict get $argd opts -parsers]
-        set argvec     [dict get $argd opts -args]
-
-        set timeit_args [list -iterations $iterations -warmup $warmup -args $argvec]
-        if {[llength $parsers] > 0} {
-            lappend timeit_args -parsers $parsers
-        }
-        set timeit_dict [timeit {*}$timeit_args]
-
-        set first_call_args {}
-        if {[llength $parsers] > 0} {
-            set first_call_args [list -parsers $parsers]
+    proc cmdline_typed {args} {
+        set cmdlineopts_typed {
+            {return.arg   "string" "return val"}
+            {frametype.arg \uFFEF "frame type"}
+            {show_edge.arg \uFFEF "show table borders"}
+            {show_seps.arg \uFFEF "show table seps"}
+            {join        "join the things"}
+            {x.arg  ""  "arg x"}
+            {y.arg  b  "arg y"}
+            {z.arg  c  "arg z"}
+            {1.boolean  1  "arg 1"}
+            {2.integer  2  "arg 2"}
+            {3.integer  3  "arg 3"}
         }
-        set first_call_dict [first_call {*}$first_call_args]
 
-        set discovered [discover_parsers]
-        set not_loaded_list {}
-        foreach {pname status} $discovered {
-            if {$status eq "not_loaded" || $status eq "not_wrappable"} {
-                lappend not_loaded_list $pname
-            }
+        set usage "usage etc"
+        set opts [::cmdline::typedGetoptions args $cmdlineopts_typed $usage]
+        if {[llength $args] != 2} {
+            error "expected exactly 2 trailing positional arguments, got [llength $args]"
         }
+        return [list [lindex $args 0] [lindex $args 1] $opts]
+    }
 
-        switch -- $fmt {
-            table {
-                set colwidth 6
-                foreach nm [dict keys $timeit_dict] {
-                    set l [string length $nm]
-                    if {$l > $colwidth} { set colwidth $l }
-                }
-                set rows {}
-                set error_names {}
-                foreach {pname timing} $timeit_dict {
-                    if {[dict exists $timing error]} {
-                        lappend error_names $pname
-                    } else {
-                        set fcold ""
-                        set fwarm ""
-                        if {[dict exists $first_call_dict $pname]} {
-                            set fdict [dict get $first_call_dict $pname]
-                            foreach {mode varname} {cold fcold warm fwarm} {
-                                if {[dict exists $fdict $mode]} {
-                                    set fval [dict get $fdict $mode]
-                                    if {[llength $fval] == 2 && [lindex $fval 0] eq "error"} {
-                                        set $varname "err"
-                                    } else {
-                                        set $varname [format %.2f $fval]
-                                    }
-                                }
-                            }
-                        }
-                        lappend rows [list [dict get $timing us_per_call] $pname [dict get $timing calls_per_sec] $fcold $fwarm [dict get $timing iterations]]
-                    }
-                }
-                set rows [lsort -real -index 0 $rows]
-                set lines {}
-                lappend lines [format "%-${colwidth}s  %12s  %14s  %10s  %10s  %10s" Parser us/call calls/sec first_cold first_warm iterations]
-                lappend lines [format "%-${colwidth}s  %12s  %14s  %10s  %10s  %10s" [string repeat - $colwidth] [string repeat - 12] [string repeat - 14] [string repeat - 10] [string repeat - 10] [string repeat - 10]]
-                foreach row $rows {
-                    lassign $row upc pname cps fcold fwarm itr
-                    lappend lines [format "%-${colwidth}s  %12.2f  %14.0f  %10s  %10s  %10d" $pname $upc $cps $fcold $fwarm $itr]
-                }
-                if {[llength $not_loaded_list] > 0} {
-                    lappend lines "not loaded: [join $not_loaded_list {, }]"
-                } else {
-                    lappend lines "not loaded: (none)"
-                }
-                if {[llength $error_names] > 0} {
-                    lappend lines "errors: [join $error_names {, }]"
-                }
-                return [join $lines \n]
-            }
-            dict {
-                return [dict create results $timeit_dict first_call $first_call_dict not_loaded $not_loaded_list]
-            }
-            json {
-                package require json::write
-                set timing_jsons [dict map {k v} $timeit_dict {
-                    if {[dict exists $v error]} {
-                        json::write object error [json::write string [dict get $v error]]
-                    } else {
-                        set jv_upc [json::write string [dict get $v us_per_call]]
-                        set jv_cps [json::write string [dict get $v calls_per_sec]]
-                        set jv_itr [json::write string [dict get $v iterations]]
-                        set jv_wu  [json::write string [dict get $v warmup]]
-                        json::write object us_per_call $jv_upc calls_per_sec $jv_cps iterations $jv_itr warmup $jv_wu
-                    }
-                }]
-                set results_json [json::write object {*}$timing_jsons]
-                set not_loaded_json [json::write array-strings {*}$not_loaded_list]
-                set fc_pairs {}
-                foreach {pname fdict} $first_call_dict {
-                    set mode_pairs {}
-                    foreach mode {cold warm} {
-                        if {[dict exists $fdict $mode]} {
-                            set fval [dict get $fdict $mode]
-                            if {[llength $fval] == 2 && [lindex $fval 0] eq "error"} {
-                                lappend mode_pairs $mode [json::write object error [json::write string [lindex $fval 1]]]
-                            } else {
-                                lappend mode_pairs $mode [json::write string $fval]
-                            }
-                        }
-                    }
-                    lappend fc_pairs $pname [json::write object {*}$mode_pairs]
-                }
-                set first_call_json [json::write object {*}$fc_pairs]
-                return [json::write object results $results_json first_call $first_call_json not_loaded $not_loaded_json]
-            }
-        }
+    namespace eval argdoc {
+        lappend PUNKARGS [list {
+            @id     -id     ::argparsingtest::tclstyle::tepam
+            @cmd    -name   argparsingtest::tclstyle::tepam   -summary "tepam procedure arg parsing, tcl style"   -help\
+                "Accepts 10 keyed options plus -join, then 2 trailing positional arguments.
+                Uses tepam::procedure with its default -named_arguments_first 1
+                (named arguments lead). Returns a list {p1 p2 optsdict}."
+            @opts   -anyopts 0
+            -return     -default string   -type string
+            -frametype  -default \uFFEF   -type string
+            -show_edge  -default \uFFEF   -type string
+            -show_seps  -default \uFFEF   -type string
+            -x          -default ""       -type string
+            -y          -default b        -type string
+            -z          -default c        -type string
+            -1          -default 1        -type boolean
+            -2          -default 2        -type integer
+            -3          -default 3        -type integer
+            -join       -type none   -multiple 1
+            @values -min 2 -max 2
+            p1          -type string   -optional 0
+            p2          -type string   -optional 0
+        }]
+    }
+    tepam::procedure {tepam} {
+    -args {
+        {-return    -type string -default string}
+        {-frametype -type string -default \uFFEF}
+        {-show_edge -type string -default \uFFEF}
+        {-show_seps -type string -default \uFFEF}
+        {-join      -type none -multiple}
+        {-x         -type string -default ""}
+        {-y         -type string -default b}
+        {-z         -type string -default c}
+        {-1         -type boolean -default 1}
+        {-2         -type integer -default 2}
+        {-3         -type integer -default 3}
+        {p1 -type string}
+        {p2 -type string}
+    }
+    } {
+        return [list $p1 $p2 [dict create return $return frametype $frametype show_edge $show_edge show_seps $show_seps x $x y $y z $z 1 $1 2 $2 3 $3 join $join]]
     }
 
     #*** !doctools
-    #[list_end] [comment {--- end definitions namespace argparsingtest ---}]
+    #[list_end] [comment {--- end definitions namespace argparsingtest::tclstyle ---}]
 }
 # ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
 
@@ -1517,7 +2281,7 @@ namespace eval argparsingtest::system {
 }
 # ++ +++ +++ +++ +++ +++ +++ +++ +++ +++ +++
 namespace eval ::punk::args::register {
-    lappend ::punk::args::register::NAMESPACES ::argparsingtest ::argparsingtest::lib
+    lappend ::punk::args::register::NAMESPACES ::argparsingtest ::argparsingtest::opts ::argparsingtest::tkstyle ::argparsingtest::tclstyle ::argparsingtest::lib
 }
 
 ##  Ready
@@ -1530,4 +2294,3 @@ return
 
 #*** !doctools
 #[manpage_end]
-
diff --git a/src/modules/argparsingtest-buildversion.txt b/src/modules/argparsingtest-buildversion.txt
index c764f805..a4b9b8ed 100644
--- a/src/modules/argparsingtest-buildversion.txt
+++ b/src/modules/argparsingtest-buildversion.txt
@@ -1,6 +1,8 @@
-0.2.0
+1.0.0
 #First line must be a semantic version number
 #all other lines are ignored.
+#1.0.0 - BREAKING restructure: parser procs moved into per-style child namespaces (argparsingtest::opts, ::tkstyle, ::tclstyle) and renamed - test1_ prefix dropped, hand-rolled parsers now share a manual_ prefix (e.g. test1_switch -> opts::manual_switch, test1_punkargs -> opts::punkargs); test1_prefix2 removed (not meaningfully distinct from test1_prefix); unused struct::set require dropped; opt/cmdline/tepam requires hoisted to module top
+#1.0.0 - new tkstyle (2 positionals first) and tclstyle (2 positionals last) parser sets returning {p1 p2 opts}; harness procs (discover_parsers/timeit/first_call/compare) gain -style and return results keyed by style; new 'unsupported' discovery status for library/style combos the backing library cannot express (cmdline in tkstyle, argp in both positional styles) - rendered as N/A rows in compare tables; external probe keys renamed (test1_getopt -> getopt etc)
 #0.2.0 - added timeit/compare/discover_parsers procs for rough parser timing comparison; PUNKARGS argdoc blocks added to all procs
 #0.2.0 - fixed timeit to call parsers with namespace-qualified name (workaround for upstream argp 0.2 caller-normalisation bug); noted the bug at the test1_argp registration site
-#0.2.0 - first_call now times cold AND warm first calls per parser (warm = backing library pre-compiled via per-library sacrificial warm-up scripts in library_warmups); replaces the punk::args-only 'punk::args::parse {} withdef {}' warm hack which was unfair to other libraries; return shape now {parser {cold <us> warm <us>}}; compare table gains first_cold/first_warm columns
\ No newline at end of file
+#0.2.0 - first_call now times cold AND warm first calls per parser (warm = backing library pre-compiled via per-library sacrificial warm-up scripts in library_warmups); replaces the punk::args-only 'punk::args::parse {} withdef {}' warm hack which was unfair to other libraries; return shape now {parser {cold <us> warm <us>}}; compare table gains first_cold/first_warm columns
diff --git a/src/tests/modules/argparsingtest/testsuites/argparsingtest/argparsingtest.test b/src/tests/modules/argparsingtest/testsuites/argparsingtest/argparsingtest.test
index 63c159f7..8a35cffd 100644
--- a/src/tests/modules/argparsingtest/testsuites/argparsingtest/argparsingtest.test
+++ b/src/tests/modules/argparsingtest/testsuites/argparsingtest/argparsingtest.test
@@ -9,13 +9,16 @@ namespace eval ::testspace {
     #added 2026-07-17 (agent) - argp is an optional package; its load-time require is guarded by catch in the module
     testConstraint argp_loaded [expr {![catch {package present argp}]}]
 
-    #added 2026-07-17 (agent)
-    test timeit_basic {Test that timeit -iterations 50 returns a dict with expected keys} -body {
-        set r [argparsingtest::timeit -iterations 50 -parsers {test1_switch}]
+    #added 2026-07-18 (agent) - suite rewritten for the argparsingtest 1.0.0 restructure:
+    #parser procs live in per-style namespaces (opts/tkstyle/tclstyle), harness results are keyed by style
+
+    #added 2026-07-18 (agent)
+    test timeit_basic {Test that timeit -style opts returns style-keyed dict with numeric timing} -body {
+        set r [argparsingtest::timeit -iterations 50 -style opts -parsers {manual_switch}]
         set ok 1
-        if {![dict exists $r test1_switch]} { set ok 0 }
+        if {![dict exists $r opts manual_switch]} { set ok 0 }
         if {$ok} {
-            set sub [dict get $r test1_switch]
+            set sub [dict get $r opts manual_switch]
             if {![dict exists $sub us_per_call]} { set ok 0 }
             if {$ok && ![string is double -strict [dict get $sub us_per_call]]} { set ok 0 }
             if {$ok && [dict get $sub iterations] != 50} { set ok 0 }
@@ -23,31 +26,119 @@ namespace eval ::testspace {
         set ok
     } -result 1
 
-    #added 2026-07-17 (agent)
-    test compare_table {Test that compare -iterations 20 -format table returns string with Parser header and not loaded footer} -body {
-        set r [argparsingtest::compare -iterations 20 -format table]
+    #added 2026-07-18 (agent)
+    test timeit_all_styles {Test that timeit default -style all times a parser under each of the three styles} -body {
+        set r [argparsingtest::timeit -iterations 20 -parsers {manual_switch}]
         set ok 1
-        if {[string first "Parser" $r] < 0} { set ok 0 }
-        if {$ok && [string first "not loaded:" $r] < 0} { set ok 0 }
+        if {[lsort [dict keys $r]] ne [lsort {opts tkstyle tclstyle}]} { set ok 0 }
+        foreach s {opts tkstyle tclstyle} {
+            if {!$ok} { break }
+            if {![dict exists $r $s manual_switch us_per_call]} { set ok "missing $s" ; break }
+            if {![string is double -strict [dict get $r $s manual_switch us_per_call]]} { set ok "non-numeric $s" ; break }
+        }
         set ok
     } -result 1
 
-    #added 2026-07-17 (agent)
-    test compare_dict {Test that compare -iterations 20 -format dict returns a dict with not_loaded and results keys} -body {
-        set r [argparsingtest::compare -iterations 20 -format dict]
+    #added 2026-07-18 (agent)
+    test timeit_nonexistent {Test that a nonexistent parser is recorded as error not re-raised} -body {
+        set r [argparsingtest::timeit -style opts -parsers {nonexistent_proc}]
         set ok 1
-        if {![dict exists $r not_loaded]} { set ok 0 }
-        if {$ok && ![dict exists $r results]} { set ok 0 }
+        if {![dict exists $r opts nonexistent_proc]} { set ok 0 }
+        if {$ok} {
+            set sub [dict get $r opts nonexistent_proc]
+            if {![dict exists $sub error]} { set ok 0 }
+        }
         set ok
     } -result 1
 
-    #added 2026-07-17 (agent)
-    test compare_json {Test that compare -iterations 20 -format json returns valid JSON with results and not_loaded keys} -body {
-        set r [argparsingtest::compare -iterations 20 -format json]
+    #added 2026-07-18 (agent)
+    test timeit_args_requires_single_style {Test that timeit -args without a single -style raises} -body {
+        set caught [catch {argparsingtest::timeit -iterations 20 -args {-x hello}} err]
+        set ok 0
+        if {$caught && [string first "single -style" $err] >= 0} {
+            set ok 1
+        }
+        set ok
+    } -result 1
+
+    #added 2026-07-18 (agent) - roster sizes: opts 16 parsers + 4 probed externals, positional styles 9 + 4
+    test discover_parsers_shape {Test discover_parsers style keying, entry counts and statuses} -body {
+        set r [argparsingtest::discover_parsers]
+        set ok 1
+        if {[lsort [dict keys $r]] ne [lsort {opts tkstyle tclstyle}]} { set ok "style keys: [dict keys $r]" }
+        if {$ok eq 1 && [dict size [dict get $r opts]] != 20} { set ok "opts size [dict size [dict get $r opts]]" }
+        if {$ok eq 1 && [dict size [dict get $r tkstyle]] != 13} { set ok "tkstyle size [dict size [dict get $r tkstyle]]" }
+        if {$ok eq 1 && [dict size [dict get $r tclstyle]] != 13} { set ok "tclstyle size [dict size [dict get $r tclstyle]]" }
+        if {$ok eq 1 && [dict get $r opts manual_switch] ne "loaded"} { set ok "opts manual_switch status" }
+        if {$ok eq 1 && [dict get $r tkstyle cmdline_typed] ne "unsupported"} { set ok "tkstyle cmdline_typed status" }
+        if {$ok eq 1 && [dict get $r tkstyle argp] ne "unsupported"} { set ok "tkstyle argp status" }
+        if {$ok eq 1 && [dict get $r tclstyle cmdline_typed] ne "loaded"} { set ok "tclstyle cmdline_typed status" }
+        if {$ok eq 1 && [dict get $r tclstyle argp] ne "unsupported"} { set ok "tclstyle argp status" }
+        if {$ok eq 1 && [dict exists $r opts test1_switch]} { set ok "stale test1_switch key present" }
+        set ok
+    } -result 1
+
+    #added 2026-07-18 (agent) - every loaded tkstyle parser honours the {p1 p2 opts} return contract
+    test parser_contract_tkstyle {Test that each loaded tkstyle parser extracts leading positionals} -body {
+        set disco [dict get [argparsingtest::discover_parsers -style tkstyle] tkstyle]
+        set ok 1
+        foreach {pname status} $disco {
+            if {$status ne "loaded"} { continue }
+            set r [argparsingtest::tkstyle::$pname alpha beta -x hello -1 0]
+            if {[lindex $r 0] ne "alpha" || [lindex $r 1] ne "beta"} {
+                set ok "$pname returned: $r"
+                break
+            }
+        }
+        set ok
+    } -result 1
+
+    #added 2026-07-18 (agent) - every loaded tclstyle parser honours the {p1 p2 opts} return contract
+    test parser_contract_tclstyle {Test that each loaded tclstyle parser extracts trailing positionals} -body {
+        set disco [dict get [argparsingtest::discover_parsers -style tclstyle] tclstyle]
         set ok 1
-        if {[catch {set d [json::json2dict $r]} _err]} { set ok 0 }
-        if {$ok && ![dict exists $d results]} { set ok 0 }
-        if {$ok && ![dict exists $d not_loaded]} { set ok 0 }
+        foreach {pname status} $disco {
+            if {$status ne "loaded"} { continue }
+            set r [argparsingtest::tclstyle::$pname -x hello -1 0 alpha beta]
+            if {[lindex $r 0] ne "alpha" || [lindex $r 1] ne "beta"} {
+                set ok "$pname returned: $r"
+                break
+            }
+        }
+        set ok
+    } -result 1
+
+    #added 2026-07-18 (agent) - N/A rows: unsupported library/style combos stay visible in the table
+    test compare_table_sections {Test that compare -format table emits all three style sections with N/A rows} -body {
+        set r [argparsingtest::compare -iterations 20 -format table -parsers {manual_switch punkargs cmdline_typed argp}]
+        set ok 1
+        foreach expected {"options only" "tk style (positionals first)" "tcl style (positionals last)" "N/A" "not loaded:" "Parser"} {
+            if {[string first $expected $r] < 0} { set ok "missing: $expected" ; break }
+        }
+        set ok
+    } -result 1
+
+    #added 2026-07-18 (agent)
+    test compare_dict {Test that compare -format dict returns style-keyed results/first_call/not_loaded/unsupported} -body {
+        set r [argparsingtest::compare -style opts -iterations 20 -parsers {manual_switch} -format dict]
+        set ok 1
+        foreach key {results first_call not_loaded unsupported} {
+            if {![dict exists $r $key]} { set ok "missing $key" ; break }
+        }
+        if {$ok eq 1 && ![dict exists $r results opts manual_switch us_per_call]} { set ok "missing results.opts.manual_switch" }
+        if {$ok eq 1 && [dict get $r unsupported opts] ne ""} { set ok "unexpected unsupported list" }
+        set ok
+    } -result 1
+
+    #added 2026-07-18 (agent)
+    test compare_json {Test that compare -format json round-trips with style-keyed unsupported and first_call structure} -body {
+        set r [argparsingtest::compare -style tkstyle -iterations 20 -parsers {manual_switch cmdline_typed} -format json]
+        set ok 1
+        if {[catch {set d [json::json2dict $r]} _err]} { set ok "json parse: $_err" }
+        if {$ok eq 1 && ![dict exists $d results tkstyle manual_switch us_per_call]} { set ok "missing results" }
+        if {$ok eq 1 && [dict get $d unsupported tkstyle] ne "cmdline_typed"} { set ok "unsupported: [dict get $d unsupported tkstyle]" }
+        if {$ok eq 1 && ![dict exists $d first_call tkstyle manual_switch cold]} { set ok "missing first_call cold" }
+        if {$ok eq 1 && ![dict exists $d first_call tkstyle manual_switch warm]} { set ok "missing first_call warm" }
         set ok
     } -result 1
 
@@ -61,23 +152,23 @@ namespace eval ::testspace {
         set ok
     } -result 1
 
-    #added 2026-07-17 (agent)
-    test discover_parsers_basic {Test that discover_parsers returns a dict with test1_switch loaded and 21 entries} -body {
-        set r [argparsingtest::discover_parsers]
-        set ok 1
-        if {![dict exists $r test1_switch]} { set ok 0 }
-        if {$ok && [dict get $r test1_switch] ne "loaded"} { set ok 0 }
-        if {$ok && [dict size $r] != 21} { set ok 0 }
+    #added 2026-07-18 (agent)
+    test compare_badstyle {Test that compare -style bogus raises an error containing choiceviolation} -body {
+        set caught [catch {argparsingtest::compare -style bogus} err]
+        set ok 0
+        if {$caught && ([string first "choiceviolation" $err] >= 0 || [string first "must be one of" $err] >= 0)} {
+            set ok 1
+        }
         set ok
     } -result 1
 
     #added 2026-07-17 (agent)
     test first_call_handrolled {Test that first_call returns cold and warm float timings for a hand-rolled parser} -body {
-        set r [argparsingtest::first_call -parsers {test1_switch}]
+        set r [argparsingtest::first_call -style opts -parsers {manual_switch}]
         set ok 1
-        if {![dict exists $r test1_switch]} { set ok 0 }
+        if {![dict exists $r opts manual_switch]} { set ok 0 }
         if {$ok} {
-            set sub [dict get $r test1_switch]
+            set sub [dict get $r opts manual_switch]
             foreach mode {cold warm} {
                 if {![dict exists $sub $mode]} { set ok 0 ; break }
                 if {![string is double -strict [dict get $sub $mode]]} { set ok 0 ; break }
@@ -88,9 +179,9 @@ namespace eval ::testspace {
 
     #added 2026-07-17 (agent)
     test first_call_library_backed {Test that first_call returns cold and warm float timings for library-backed parsers (warm-up scripts must run cleanly)} -body {
-        set r [argparsingtest::first_call -parsers {test1_punkargs test1_punkargs_by_id test1_opt test1_cmdline_untyped test1_cmdline_typed test1_tepam}]
+        set r [argparsingtest::first_call -style opts -parsers {punkargs punkargs_by_id opt cmdline_untyped cmdline_typed tepam}]
         set ok 1
-        foreach {pname sub} $r {
+        foreach {pname sub} [dict get $r opts] {
             foreach mode {cold warm} {
                 if {![dict exists $sub $mode]} { set ok "missing $mode for $pname" ; break }
                 if {![string is double -strict [dict get $sub $mode]]} { set ok "$pname $mode: [dict get $sub $mode]" ; break }
@@ -100,10 +191,27 @@ namespace eval ::testspace {
         set ok
     } -result 1
 
+    #added 2026-07-18 (agent) - positional-style parsers must also time cleanly in child interps
+    test first_call_positional_styles {Test first_call cold and warm for tkstyle and tclstyle parsers} -body {
+        set ok 1
+        foreach {s plist} {tkstyle {punkargs_by_id tepam} tclstyle {cmdline_untyped}} {
+            set r [argparsingtest::first_call -style $s -parsers $plist]
+            foreach {pname sub} [dict get $r $s] {
+                foreach mode {cold warm} {
+                    if {![dict exists $sub $mode]} { set ok "missing $mode for $s $pname" ; break }
+                    if {![string is double -strict [dict get $sub $mode]]} { set ok "$s $pname $mode: [dict get $sub $mode]" ; break }
+                }
+                if {$ok ne 1} { break }
+            }
+            if {$ok ne 1} { break }
+        }
+        set ok
+    } -result 1
+
     #added 2026-07-17 (agent)
-    test first_call_argp {Test first_call cold and warm for test1_argp when argp is loaded} -constraints argp_loaded -body {
-        set r [argparsingtest::first_call -parsers {test1_argp}]
-        set sub [dict get $r test1_argp]
+    test first_call_argp {Test first_call cold and warm for argp when argp is loaded} -constraints argp_loaded -body {
+        set r [argparsingtest::first_call -style opts -parsers {argp}]
+        set sub [dict get $r opts argp]
         set ok 1
         foreach mode {cold warm} {
             if {![string is double -strict [dict get $sub $mode]]} { set ok "$mode: [dict get $sub $mode]" ; break }
@@ -113,33 +221,11 @@ namespace eval ::testspace {
 
     #added 2026-07-17 (agent)
     test compare_table_first_columns {Test that compare table output has first_cold and first_warm columns} -body {
-        set r [argparsingtest::compare -iterations 20 -format table -parsers {test1_switch}]
+        set r [argparsingtest::compare -style opts -iterations 20 -format table -parsers {manual_switch}]
         set ok 1
         if {[string first "first_cold" $r] < 0} { set ok 0 }
         if {$ok && [string first "first_warm" $r] < 0} { set ok 0 }
         set ok
     } -result 1
-
-    #added 2026-07-17 (agent)
-    test compare_json_first_call_structure {Test that compare json first_call entries are objects with cold and warm keys} -body {
-        set r [argparsingtest::compare -iterations 20 -format json -parsers {test1_switch}]
-        set d [json::json2dict $r]
-        set ok 1
-        if {![dict exists $d first_call test1_switch cold]} { set ok 0 }
-        if {$ok && ![dict exists $d first_call test1_switch warm]} { set ok 0 }
-        set ok
-    } -result 1
-
-    #added 2026-07-17 (agent)
-    test timeit_nonexistent {Test that a nonexistent parser is recorded as error not re-raised} -body {
-        set r [argparsingtest::timeit -parsers {nonexistent_proc}]
-        set ok 1
-        if {![dict exists $r nonexistent_proc]} { set ok 0 }
-        if {$ok} {
-            set sub [dict get $r nonexistent_proc]
-            if {![dict exists $sub error]} { set ok 0 }
-        }
-        set ok
-    } -result 1
 }
 tcltest::cleanupTests